# Source maps available

- **Pattern:** `ab-002378` (`sdk-package-quality.build-distribution.source-maps`)
- **Severity:** low
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-002378
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-002378)

## Why it matters

When a consumer encounters a bug that originates inside your package, their stack trace shows transpiled or minified output — line numbers and variable names from `dist/index.cjs` line 1 that bear no resemblance to the original source. Without source maps, debugging requires manually cloning your repo, matching the version, and mapping the call site. ISO 25010 analysability degrades directly: the time-to-understand a stack trace goes from seconds to minutes.

## Severity rationale

Low because source maps affect debugging ergonomics only — the absence does not cause runtime failures, and determined consumers can still diagnose issues by reading the compiled output.

## Remediation

Enable source map generation in your build tool and include the `.map` files in the published package.

```ts
// tsup.config.ts:
import { defineConfig } from 'tsup'
export default defineConfig({ sourcemap: true })
```

```json
// tsconfig.json — for declaration maps:
{
  "compilerOptions": { "declarationMap": true }
}
```

Verify that `.js.map` files appear in `dist/` after building and that your `files` field in `package.json` includes the `dist` directory (so maps are published). At least one `.map` file must be present in the published package for this check to pass.

## Detection

- **ID:** `source-maps`
- **Severity:** `low`
- **What to look for:** Count all published JavaScript files. For each, check if the build produces source maps:
  1. `.map` files in `dist/` directory
  2. `sourcemap: true` in build tool config (tsup, rollup, esbuild)
  3. `declarationMap: true` in `tsconfig.json` (for `.d.ts.map` files)
  4. `//# sourceMappingURL=` comments at the end of built files
- **Pass criteria:** Source maps (`.js.map` and/or `.d.ts.map`) are generated and included in the published package, allowing consumers to debug through to the original source when needed — at least 1 source map file must be included for debugging support. Report: "X JS files published, Y include source maps."
- **Fail criteria:** No source maps generated. Consumers debugging issues in their application will see minified or transpiled code in stack traces and debuggers.
- **Skip (N/A) when:** The package output is human-readable without source maps (e.g., the build tool produces clean, unminified output that closely matches the source). Also skip for Python (source IS the distribution) and Go (source IS the distribution).
- **Detail on fail:** `"No source maps generated. tsup.config.ts has sourcemap: false (or absent). Consumers debugging issues will see transpiled output instead of original TypeScript source in stack traces."`
- **Remediation:** Source maps help consumers debug issues involving your package without needing to clone your repo.

  ```ts
  // tsup.config.ts:
  export default defineConfig({
    sourcemap: true,
    // ...
  })
  ```

  ```json
  // tsconfig.json — for declaration maps:
  {
    "compilerOptions": {
      "declarationMap": true
    }
  }
  ```

## External references

- iso-25010 maintainability.analysability

Taxons: user-experience

HTML version: https://auditbuffet.com/patterns/ab-002378