Replace tsup with tsdown

[chrispcampbell]

We've been using tsup for a long time to bundle our TS libraries, but it is no longer actively maintained. The recommended replacement is tsdown, which is built on rolldown.

We should replace tsup with tsdown. This will avoid issues related to outdated dependencies (for example, it will remove the underlying dependency on esbuild). There is a migration tool, and the impact on our published libraries should be minimal.

[chrispcampbell]

As part of this, I removed the legacy CJS from the generated docs-builder library, so we only ship ESM now, which should be fine for the places where it is used.

---

Adding Claude's notes for the record.

Click to show notes

Notes: Replace tsup with tsdown (#138)

Three commits on chris/137-lockfile-refresh:

Commit	Summary
1ba4c6c	build: replace tsup with tsdown
04f668d	build: drop the CommonJS build output
c01eb98	build: use the default tsdown output file extensions

What changed

Build tool

tsup is replaced by tsdown 0.23.0 (built on rolldown). tsup.config.ts becomes
tsdown.config.ts, and the build / watch scripts now run tsdown rather than
tsup-node — there is no tsdown-node binary, so the Node target is expressed as
platform: 'node' in the config instead.

The final config only carries options that differ from the tsdown defaults:

export default defineConfig({
  tsconfig: 'tsconfig.json',
  entry: ['src/index.ts'],
  format: ['esm'],
  platform: 'node',
  dts: { sourcemap: true },
  sourcemap: true,
  clean: true
})

The shims: true option from the tsup config is gone. tsdown always shims
import.meta.url in CommonJS output regardless of that flag, and nothing in src uses
__dirname / __filename in a way that needs the reverse shim into ESM.

esbuild is gone

This was the concrete goal in the issue. Verified by wiping node_modules and
reinstalling with --frozen-lockfile: no esbuild anywhere in the tree. The now-dead
esbuild entry was removed from onlyBuiltDependencies in pnpm-workspace.yaml.

Note that esbuild still appears in pnpm-lock.yaml, but only as an optional peer
dependency of vite — there is no resolution block for it, so nothing installs it.

ESM only

The CommonJS bundle is dropped, since the package is only consumed from ESM contexts.
dist/ went from eight files to four.

Output file names

Ended up on tsdown's defaults: index.mjs, index.mjs.map, index.d.mts,
index.d.mts.map.

An intermediate step (1ba4c6c) used a custom outExtensions to keep tsup's .js /
.d.ts names, then c01eb98 removed it. Anything referencing the old paths had to move:
main, types, exports, and — easy to miss — the import in bin/cli.js, which
reaches into ../dist/index.mjs directly.

tsconfig: moduleResolution "node" → "bundler"

Required, not cosmetic. tsdown declares its types only under an exports field as
.d.mts, which the legacy node resolver cannot see, so tsc --noEmit failed on
tsdown.config.ts itself. The whole package type-checks clean under bundler.

Things to be aware of

This is a breaking change for CommonJS consumers. A require('@climateinteractive/docs-builder')
now fails with ERR_PACKAGE_PATH_NOT_EXPORTED instead of returning a working bundle.
All three commits are typed build:, which release-please will treat as a patch bump. If
that should be signalled as breaking, a commit needs a ! or a BREAKING CHANGE: footer.

Declaration source maps are new. With plain dts: true, tsdown writes a
//# sourceMappingURL=index.d.mts.map comment into the declaration file but does not emit
the map — a dangling reference in the published package. Setting dts: { sourcemap: true }
emits the two ~0.5 kB map files. This is the one output difference versus tsup, which
emitted neither the comment nor the maps.

Consumers on legacy moduleResolution: "node" are fine, despite the .d.mts types.
The package declares an explicit top-level types field, which the legacy resolver reads
directly. This is exactly what tsdown itself does not do, which is why it broke our own
type-check.

Verification

• ./scripts/ci-build (full monorepo) passes: clean, lint, prettier, type-check,
  34/34 tests, build — plus the sample-docs example, which runs the docs-builder bin
  end to end and produces HTML, hashed assets, and puppeteer PDFs for both en and de.
• Resolved the package by name from examples/sample-docs, i.e. through the exports
  map rather than a file path, and got all five expected exports.
• Type-checked a consumer importing the package under moduleResolution node,
  bundler, and node16 — all clean.
• Diffed the generated .d.ts against the tsup output back when the names still matched:
  identical exported names and types, only formatting differs.
• Confirmed the CJS import.meta.url shim resolved to the real dist directory while the
  CommonJS build still existed — build.ts uses __dirname as the findUp starting point
  for locating assets in node_modules, so a wrong value there would have broken asset
  copying silently.