feat!: switch to ESM and native TypeScript type-stripping

[Tony133]

Proposal:

Follow-up to #159, as discussed with @mcollina:

I would recommend we switch to strip types and esm

Changed:

• src/index.ts rewritten to ESM (export default), the old export = / import = require() syntax isn't "erasable" and
  breaks Node's native type-stripping.
• tsconfig.json updated per Node's official recommended settings for type-stripping (module: nodenext, verbatimModuleSyntax, erasableSyntaxOnly, allowImportingTsExtensions, rewriteRelativeImportExtensions).
• Relative imports now use explicit .ts extensions in source; tsc rewrites them to .js in the compiled lib/ output.
• test/index.test.ts: __dirname → import.meta.dirname, type-only imports (TestContext, Session, SessionData) marked with type per verbatimModuleSyntax.
• package.json: "type": "module", added "exports" map, bumped engines to >=20.19.0 <21 || >=22.12.0.
• Update README.md

Breaking change:

This is now an ESM-only package. require() from CommonJS consumers still works, since it relies on Node's require(esm) support, stable as of Node 20.19.0 / 22.12.0. Consumers on older Node versions will need to upgrade.

Note:

• Requires a major version bump ( v7.0.0 )

[Tony133]

cc @fastify/typescript

[mcollina]

likely there is something to fix in the tsconfig.build.json

[mcollina]

why?

[Tony133]

Just to confirm, you mean main/types are redundant now that exports is present, right? 😅

-  "main": "./lib/index.js",
   "type": "module",
-  "types": "./lib/index.d.ts",
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
       "default": "./lib/index.js"
     }
   },

[climba03003]

why using exports when you only have single entrypoint?

[Tony133]

why using exports when you only have single entrypoint?

The only advantage, now that I think about it is: "encapsulation".
The exports field explicitly defines the package's public interface. Without it, nothing prevents a user from running require('@fastify/flash/lib/flash.js') and depending on an internal file. With exports, that import throws ERR_PACKAGE_PATH_NOT_EXPORTED, so we're free to restructure the internals of lib/ later without it being a breaking change.

That said, we could also just drop it and keep this instead:

   "main": "./lib/index.js",
   "type": "module",
   "types": "./lib/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/index.d.ts",
-      "default": "./lib/index.js"
-    }
-  },

Happy to go either way, let me know which you'd prefer 😉

[mcollina]

Is this building correctly for release? is tsconfig.build.json correct?

[Tony133]

Yes, verified locally on Node 24.18.0. Commands to reproduce:

npm run build
ls -la lib/
node -e "require('./lib/index.js'); console.log('require(esm) works')"

Output:

• lib/index.js, lib/index.d.ts, lib/flash.js, lib/flash.d.ts produced
• lib/index.js matches exports["."].default
• lib/index.d.ts matches exports["."].types
• require('./lib/index.js') resolves and logs "require(esm) works" confirms the exports map works for CJS consumers too

tsconfig.build.json is correct: its include: ["src"] overrides(not merges with) the base config's broader include, so test/ is correctly excluded and only the paths declared in exports get produced.

---