Your frontend code builds cleanly under Vite or esbuild, but running tsc --noEmit in CI explodes with dozens of import errors. You set "moduleResolution": "bundler" in your shared base configuration to make imports easy, and now your Node-based scripts, Vitest configs, or backend packages resolve types that fail completely at runtime.

Here is the build failure that usually shows up in CI when tsconfig.json lies about how the runtime actually loads your code:

text
src/server/index.ts:2:24 - error TS2835: Relative import paths need explicit file extensions in EcmaScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './database.js'?

2 import { getPool } from './database';
                          ~~~~~~~~~~~~

src/server/worker.ts:5:8 - error TS2307: Cannot find module '@shared/utils' or its corresponding type declarations.

5 import { parsePayload } from '@shared/utils';
                               ~~~~~~~~~~~~~~~~

The underlying issue is a mismatch between bundler assumptions and Node’s strict ESM loader. When you set "moduleResolution": "bundler", TypeScript stops enforcing file extensions on relative imports, respects the browser field or custom export conditions in package.json, and allows directory imports like ./services instead of ./services/index.js. That works if your target is Webpack, Vite, or Rollup. It falls apart the second Node executes that code directly through tsx, ts-node, or after compiling with tsc.

Node’s native ESM requires explicit file extensions in relative specifiers, respects package.json conditional exports strictly, and does not automatically resolve directory indexes. When your base configuration chooses convenience over correctness, you build a mental model of your imports that runtime environments reject.

The Real Difference Between nodenext and bundler

TypeScript provides two modern resolution strategies: nodenext (and its alias node16) and bundler. They are not interchangeable.

moduleResolution: "nodenext" forces your type checker to mimic Node’s native module loader. It looks at the nearest package.json to determine if a file is CommonJS or ESM based on the "type": "module" field. It forces you to write relative imports pointing to the emitted .js extension, even while you are writing TypeScript:

typescript
// Correct under nodenext when database.ts sits on disk
import { getPool } from './database.js';

moduleResolution: "bundler" was introduced in TypeScript 5.0. It models the behavior of modern bundlers like Vite, esbuild, and Webpack 5. It allows extensionless imports, lets you import TypeScript files directly using .ts extensions if allowImportingTsExtensions is set, and resolves exports from packages using the types condition alongside custom conditions defined in your bundler configuration. It does not enforce Node’s strict runtime rules.

If you are shipping a library, writing backend services executed directly by Node, or sharing code between a web app and a Node background worker, using bundler in your root config is a trap. It lets you write invalid Node ESM imports that type-check locally but break in production.

Here is what a broken, permissive setup looks like:

json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

This configuration tells TypeScript: assume an external bundler will resolve any path syntax, resolve index files automatically, ignore extensions, and rewrite path aliases into disk locations. Node will do none of these things out of the box.

Structuring tsconfig for Hybrid Repositories

If you have a project with both bundled frontend code and unbundled Node processes, do not share a single resolution setting. Separate them using project references or explicit child configurations.

Start with a strict shared base that enforces language safety without locking in a flawed module resolution scheme.

base.json

json
{
  "$schema": "https://json.schemastore.org/tsconfig",
  "compilerOptions": {
    "target": "ES2022",
    "strict": true,
    "strictNullChecks": true,
    "noImplicitOverride": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "exactOptionalPropertyTypes": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true
  }
}

Notice that module and moduleResolution are deliberately omitted here.

tsconfig.node.json

Use this for backend services, CLI tools, migration scripts, and any code executed directly by Node:

json
{
  "$schema": "https://json.schemastore.org/tsconfig",
  "extends": "./base.json",
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}

In your package.json, set:

json
{
  "type": "module"
}

With NodeNext, TypeScript requires you to reference ./database.js even though the source file is database.ts. TypeScript emits the JS file with that exact string specifier, which allows Node’s native ESM resolver to locate the file on disk without runtime path patching.

tsconfig.web.json

Use this strictly for code processed by Vite, Turbopack, or another bundler:

json
{
  "$schema": "https://json.schemastore.org/tsconfig",
  "extends": "./base.json",
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "noEmit": true,
    "allowSyntheticDefaultImports": true
  },
  "include": ["src/**/*"]
}

Now frontend developers get the ergonomics of bundler resolution where a bundler actually exists, while the backend code is protected against invalid imports.

The Path Alias Trap

A common source of late-night frustration is assuming that setting paths in tsconfig.json makes aliases work at runtime.

json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@shared/*": ["packages/shared/src/*"]
    }
  }
}

The TypeScript compiler does not rewrite paths. It resolves types during compilation and leaves the import string identical in the emitted JavaScript:

typescript
// src/index.ts
import { logMessage } from '@shared/logger.js';

Compiles directly to:

javascript
// dist/index.js
import { logMessage } from '@shared/logger.js';

When Node runs dist/index.js, it throws ERR_MODULE_NOT_FOUND because @shared is not an npm package in node_modules.

The Native Fix: Subpath Imports

Stop using compilerOptions.paths for code executed by Node. Use Node’s native Subpath Imports instead, which are supported in Node 14.6+ and understood natively by TypeScript when using moduleResolution: "nodenext" or "bundler".

In your package.json, add an imports field. All subpath imports must begin with #:

json
{
  "name": "my-application",
  "type": "module",
  "imports": {
    "#shared/*": "./dist/shared/*",
    "#shared/*.ts": "./src/shared/*"
  }
}

For development and local build setups where you compile from src to dist, you can point the import directly to your build structure, or use conditional imports:

json
{
  "name": "my-application",
  "type": "module",
  "imports": {
    "#services/*": {
      "types": "./src/services/*.ts",
      "default": "./dist/services/*.js"
    }
  }
}

Now in your code:

typescript
import { authService } from '#services/auth.js';

Both TypeScript and Node resolve this natively without third-party path rewriting tools like tsconfig-paths or custom loader hooks. No paths configuration in tsconfig.json is required.

Pitfall: strictNullChecks with exactOptionalPropertyTypes

Many developers turn on "strict": true and assume their null-safety is fully dialed in. It is not. Consider this interface:

typescript
interface UserProfile {
  id: string;
  bio?: string;
}

Under standard "strict": true, TypeScript enables strictNullChecks. However, strictNullChecks treats an optional property as:

typescript
bio?: string | undefined

This allows code like this to pass type-checking:

typescript
const profile: UserProfile = {
  id: "usr_100",
  bio: undefined
};

console.log("bio" in profile); // true
console.log(Object.keys(profile)); // ['id', 'bio']

In JavaScript, a key present with a value of undefined behaves differently than a missing key. This routinely breaks code using Object.assign, spread operators, and database updates where { bio: undefined } attempts to write NULL to a SQL column, whereas an omitted property leaves the column untouched.

To prevent this, add "exactOptionalPropertyTypes": true to your configuration:

json
{
  "compilerOptions": {
    "strict": true,
    "exactOptionalPropertyTypes": true
  }
}

Now, TypeScript forces callers to differentiate between omitting the property and passing an explicit undefined:

typescript
interface UserProfile {
  id: string;
  bio?: string;
}

const profile: UserProfile = {
  id: "usr_100",
  // Error: Type 'undefined' is not assignable to type 'string' with 'exactOptionalPropertyTypes: true'.
  bio: undefined
};

If you actually want to permit explicit undefined, you must declare it intentionally:

typescript
interface UserProfile {
  id: string;
  bio?: string | undefined;
}

Pitfall: Third-Party Packages Without types in package.json Exports

When migrating to moduleResolution: "nodenext", you will run into third-party libraries that fail to resolve, even if their type definitions are sitting inside node_modules.

This happens when a library uses modern exports in their package.json, but forgets to add the types condition, or puts the types condition in the wrong order. Node ignores types, but TypeScript’s nodenext resolver reads the exports map strictly. If types is not declared inside an export branch, TypeScript treats the module as having no type definitions.

Example of a broken dependency package.json:

json
{
  "name": "faulty-lib",
  "exports": {
    ".": {
      "import": "./index.mjs",
      "require": "./index.cjs"
    }
  },
  "types": "./index.d.ts"
}

Under nodenext, TypeScript ignores the root "types": "./index.d.ts" field because the package defined an "exports" map. The exports map takes precedence.

To fix this without waiting for the upstream maintainer to merge a PR, use module declaration augmentation in a local declaration file (for instance, src/types/patches.d.ts):

typescript
declare module 'faulty-lib' {
  export function runTask(): Promise<void>;
}

Alternatively, you can create a declaration file alongside your imports using path mapping strictly for that broken module in your tsconfig.json:

json
{
  "compilerOptions": {
    "paths": {
      "faulty-lib": ["./node_modules/faulty-lib/index.d.ts"]
    }
  }
}

This bypasses the strict package.json export lookup for that package while keeping nodenext enforcement intact for the rest of your project.

Verification

To verify that your configuration is sound across both compilation and runtime execution, run a two-stage check in your terminal.

First, check that TypeScript emits no errors under strict resolution:

bash
npx tsc --project tsconfig.node.json --noEmit

Second, compile the code to disk and execute it directly with Node to verify that all relative imports, file extensions, and subpath imports work without bundler intervention:

bash
npx tsc --project tsconfig.node.json
node dist/index.js

If Node launches your entry point without emitting ERR_MODULE_NOT_FOUND or ERR_UNKNOWN_FILE_EXTENSION, your module resolution strategy mirrors the real environment your code runs in.

More in TypeScript