Skip to content

fix(build): bundle type declarations so they resolve under node16/nodenext - #23

Open
jdrhyne wants to merge 1 commit into
mainfrom
fix/dts-node16-resolution
Open

jdrhyne wants to merge 1 commit into
mainfrom
fix/dts-node16-resolution

Conversation

@jdrhyne

@jdrhyne jdrhyne commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

Summary

The package is "type": "module", and the build emitted per-file .d.ts files with extensionless relative imports (from './client'). TypeScript can't resolve those under moduleResolution: node16 or nodenext, so every export silently became any for consumers using those modes. CommonJS consumers were also handed the ESM declarations.

Type of Change

  • Bug fix (non-breaking change which fixes an issue)

Changes Made

  • tsup.config.ts: bundle declarations into dist/index.d.ts (ESM) and dist/index.d.cts (CommonJS). ignoreDeprecations: '6.0' is set for the declaration build only, because tsup's declaration bundler sets baseUrl, which TypeScript 6 deprecates. The project tsconfig is unchanged.
  • package.json: the import and require conditions each point at their own declaration file; the separate tsc --project tsconfig.types.json build step is removed.
  • tsconfig.types.json: removed (no longer used).
  • tools/smoke-test.mjs: type-checks a consumer against the packed tarball under nodenext, node16 (ESM and CommonJS) and bundler, with skipLibCheck: false. @ts-expect-error guards fail if the exports resolve to any.
  • .github/workflows/ci.yml: run the smoke test on pull requests (it previously ran only at release) and check that dist/index.d.cts exists.
  • CHANGELOG.md: Unreleased → Fixed entry.

Related Issues

Fixes #22

Testing

Revert check: with package.json and tsup.config.ts restored from main and the package rebuilt, npm run test:smoke exits 1 with TS2834 ("Relative import paths need explicit file extensions...") on dist/index.d.ts, plus consumer.cts(3,1): error TS2578: Unused '@ts-expect-error' directive. (the silent any). With the fix it passes all three resolution modes.

Run locally (macOS, Node 22.16.0, TypeScript 6.0.3):

  • npm run typecheck ✅
  • npm run lint ✅
  • npm run test:unit ✅ 315/315
  • npm run build ✅
  • npm run test:smoke ✅

Not run: CI matrix (Linux, Windows) — pending on this PR.
Not run: TypeScript 7 — the repository pins ^6.0.3.
Not run: arethetypeswrong — not installed in the repository.

Notes for reviewers

  • Bundled declarations have no declaration maps, so "go to definition" lands in dist/index.d.ts rather than src/.
  • tsup's declaration bundling uses the TypeScript JS API; moving to TypeScript 7 may require replacing it (for example, explicit .js extensions on the relative imports in src/ and moduleResolution: nodenext).

…enext

The package is "type": "module", and the build emitted per-file .d.ts files
with extensionless relative imports (from './client'). TypeScript cannot
resolve those under moduleResolution node16 or nodenext, so every export
silently became `any` for consumers using those modes. CommonJS consumers
were also handed the ESM declarations.

- tsup now bundles declarations into dist/index.d.ts (ESM) and
  dist/index.d.cts (CommonJS); the separate tsc declaration step and
  tsconfig.types.json are removed. ignoreDeprecations is set for the
  declaration build only, because tsup's bundler sets baseUrl, which
  TypeScript 6 deprecates.
- The exports map points the import and require conditions at their own
  declaration files.
- The packed-tarball smoke test now type-checks a consumer under nodenext,
  node16 (ESM and CommonJS) and bundler, with @ts-expect-error guards that
  fail if the exports resolve to `any`.
- CI runs the smoke test on pull requests, not only at release.

Fixes #22

Revert check: with package.json and tsup.config.ts restored from main and
the package rebuilt, `npm run test:smoke` exits 1 with TS2834 ("Relative
import paths need explicit file extensions...") on dist/index.d.ts and
consumer.cts(3,1): error TS2578: Unused '@ts-expect-error' directive.
With the fix it passes all three resolution modes.

Checks run locally (macOS, Node 22.16.0, TypeScript 6.0.3): npm run
typecheck, npm run lint, npm run test:unit (315/315), npm run build,
npm run test:smoke.

Not run: CI matrix (Linux, Windows) - pending on this push.
Not run: TypeScript 7 - the repository pins ^6.0.3.
Not run: arethetypeswrong - not installed in the repository.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bug: published .d.ts files lack file extensions on relative imports, breaking types under moduleResolution node16/nodenext

1 participant