NodeNext module resolution for Node-run and published code

Rule

Set module and moduleResolution to NodeNext. Write every relative import with a .js extension, even though the source file is .ts. Do not use paths aliases; tsc does not rewrite them in emitted code.

Do

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

import { tokenize } from './tokenize.js';
import type { Query } from './types.js';

Don’t

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

import { tokenize } from './tokenize';
import { score } from '@/bm25';

Rationale

These repos run in Node or publish to npm, where ESM requires full relative specifiers. bundler resolution accepts extensionless imports that then fail for every consumer that does not bundle. Under NodeNext, a missing extension is a typecheck error.

Related

• STD-TS-003: the setting for bundled apps
• CGD-01
• TypeScript & ESLint Standards