How TypeScript 5.7's --module nodenext Changes Are Breaking Legacy Express Apps (and How to Fix Them)

Most Express app TypeScript failures after upgrading to 5.7 stem from three enforcement changes in --module nodenext that break previously tolerated patterns. Teams discover this when builds that passed in 5.6 suddenly throw module resolution errors with no obvious code changes.

The breaking point arrived when TypeScript 5.7 tightened nodenext mode to match Node.js's actual ESM/CommonJS behavior. Apps that mixed module systems or imported JSON without explicit configuration now fail at compile time. This distinction is critical: the errors surface before runtime, but only after you upgrade.

Understanding the --module nodenext Mode and What Changed in 5.7

TypeScript's nodenext module mode tells the compiler to follow Node.js's native module resolution rules exactly. Before 5.7, the compiler permitted several patterns that Node.js would reject at runtime. The 5.7 release closed those gaps.

TypeScript 5.7 module resolution enforcement flow

Node.js treats files with a .js extension differently depending on the nearest package.json's type field. When type: "module" is set, .js files are ESM. Without it, they're CommonJS. TypeScript 5.7's nodenext mode now enforces this distinction at compile time instead of allowing mismatches to slip through.

The implication here is that Express apps built with implicit CommonJS assumptions break immediately. Most legacy Express codebases don't declare type: "module" and use .ts files that compile to CommonJS .js outputs. When those apps import ESM-only packages or omit file extensions, TypeScript 5.7 stops compilation.

TypeScript module resolution comparison

The Three Breaking Changes Hitting Express Apps Hard

The breaking changes cluster around three patterns that TypeScript previously allowed but Node.js would reject. Each pattern represents a common Express app structure that worked in TypeScript 5.6 but fails in 5.7 with nodenext enabled.

Three TypeScript 5.7 breaking change categories

First, require() calls to ESM-only packages now fail at compile time. Many Express apps use require() to load dependencies synchronously during server initialization. When those dependencies are ESM-only, Node.js throws a runtime error. TypeScript 5.7 catches this earlier.

Second, importing JSON files without resolveJsonModule: true in tsconfig.json now produces a compile error. Express apps frequently import configuration files or package.json for version strings. The compiler no longer assumes JSON imports are valid without explicit configuration.

Third, relative imports missing the .js extension fail in nodenext mode. This catches developers off guard because TypeScript files use .ts extensions but must import with .js extensions when targeting ESM output. The mismatch between source and output extensions is a longstanding Node.js ESM requirement.

Error Case 1: require() Calls to ESM Modules Are Now Forbidden

The most common failure mode appears when Express apps attempt to require() an ESM-only package. This occurs frequently with newer middleware packages that dropped CommonJS builds.

// ❌ This fails in TypeScript 5.7 with nodenext
const helmet = require('helmet'); // Error: Cannot require() an ESM-only module

app.use(helmet());

The error message is explicit: "The current file is a CommonJS module whose imports will produce 'require' calls; however, the referenced file is an ESM module and cannot be imported with 'require'."

The fix requires either converting to dynamic import() or downgrading to a CommonJS-compatible package version:

// ✅ Option 1: Use dynamic import (requires async context)
const helmetPromise = import('helmet').then(m => m.default);

app.use(async (req, res, next) => {
  const helmet = await helmetPromise;
  return helmet()(req, res, next);
});

// ✅ Option 2: Use a CommonJS build (check package.json exports)
const helmet = require('helmet/dist/cjs/index.js');
app.use(helmet());

The tradeoff here is clear: dynamic imports add complexity but maintain forward compatibility. Pinning to CommonJS builds is simpler but locks you to older package versions. For production Express apps, the CommonJS approach typically wins because it avoids refactoring middleware initialization logic.

Error Case 2: Stricter JSON Import Rules Breaking Middleware Configs

Express apps routinely import JSON configuration files for environment-specific settings. TypeScript 5.7 now requires explicit compiler permission for these imports.

// ❌ Fails without resolveJsonModule: true
import config from './config.json';

app.listen(config.port);

The error states: "Cannot find module './config.json'. Consider using '--resolveJsonModule' to import module with '.json' extension."

The fix is straightforward but requires a tsconfig.json change that affects the entire project:

// tsconfig.json
{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "resolveJsonModule": true, // ✅ Add this
    "esModuleInterop": true
  }
}

// ✅ Now this works
import config from './config.json';

This matters because enabling resolveJsonModule changes how TypeScript treats all JSON imports project-wide. The compiler now validates JSON structure against the imported type, catching configuration errors at compile time instead of runtime.

JSON module resolution in TypeScript 5.7

Error Case 3: Missing .js Extensions in Import Paths Now Fail

The extension requirement trips up developers because TypeScript source files use .ts but must import with .js when targeting ESM. This reflects Node.js ESM behavior, not a TypeScript quirk.

// ❌ Fails in nodenext mode
import { UserService } from './services/user-service';

// ✅ Must include .js extension (even though file is user-service.ts)
import { UserService } from './services/user-service.js';

The error reads: "Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'nodenext'."

This breaking change forces explicit imports across the entire codebase. Automated tools help, but the migration still requires careful review to avoid breaking relative path structures. Teams often underestimate the scope—large Express apps can have hundreds of relative imports.

The Complete Fix: Migrating Your Express App to TypeScript 5.7

The migration path depends on whether your app can move to ESM or must remain in CommonJS. Most legacy Express apps stay in CommonJS until dependencies and tooling fully support ESM.

TypeScript 5.7 Express migration workflow

For CommonJS apps, the minimal fix preserves existing patterns while satisfying TypeScript 5.7:

// tsconfig.json for CommonJS apps
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",           // Stay in CommonJS
    "moduleResolution": "node",     // Classic Node resolution
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

This configuration avoids nodenext mode entirely, bypassing the strict ESM enforcement. The tradeoff is that you lose compile-time validation of Node.js ESM compatibility. For apps with no ESM migration timeline, this is the pragmatic choice.

For apps ready to migrate to ESM, the path requires coordinated changes across package.json, tsconfig.json, and every source file. The Node.js ESM migration guide covers the full process, but the core steps are:

1. Set "type": "module" in package.json
2. Set "module": "nodenext" in tsconfig.json
3. Add .js extensions to all relative imports
4. Convert all require() calls to import statements
5. Update middleware initialization to handle async imports

The failure mode here is subtle but expensive: incomplete migrations leave the app in a broken state where some modules load correctly and others fail at runtime. Automated testing catches most issues, but edge cases in dynamic require() patterns often slip through.

When to Use --module nodenext vs commonjs in 2026

The decision between nodenext and commonjs depends on deployment constraints and dependency compatibility. Teams must evaluate both technical and organizational factors.

Module mode decision comparison for Express apps

Use module: "commonjs" when:

• The app has no near-term ESM migration plan
• Critical dependencies lack ESM builds
• The team prioritizes stability over forward compatibility
• Deployment infrastructure doesn't support Node.js ESM yet

Use module: "nodenext" when:

• The app is greenfield or actively maintained
• All dependencies provide ESM builds
• The team can handle the extension and async import requirements
• You need compile-time validation of Node.js module compatibility

The distinction is critical for legacy Express apps: switching to nodenext without preparation breaks builds immediately. The compiler will surface every incompatible pattern at once, forcing emergency fixes or a rollback. Teams shipping to production need a staged migration with comprehensive testing before enabling nodenext.

For new Express apps in 2026, nodenext is the correct default. The Node.js ecosystem has largely moved to ESM, and TypeScript's stricter enforcement catches module errors before they reach production. The upfront cost of adding extensions and using async imports pays off in reduced runtime failures.

The Node.js 24 native TypeScript support enables running .ts files directly in production, but this only works when the TypeScript configuration matches Node.js's actual module behavior. Apps using nodenext mode get this compatibility automatically.

That covers the essential patterns for migrating Express apps to TypeScript 5.7's stricter module resolution. Apply these fixes in production and the difference will be immediate: fewer runtime module errors, clearer compile-time feedback, and forward compatibility with the Node.js ESM ecosystem. The TypeScript 6 release builds on these foundations, so getting the module configuration right now prevents future upgrade pain.

Comments

[Frank]

This is a crucial heads-up!