TypeScript 5.7: Isolated Declarations, Path Rewriting, and --noUncheckedSideEffectImports

TypeScript 5.7 released on November 22, 2024. The release focuses on build performance, better compatibility with native Node.js TypeScript stripping, and stricter import validation. None of the changes are breaking for existing code — all new flags are opt-in.

>Isolated Declarations — parallel type emit

The --isolatedDeclarationsflag enforces that each file's exports can have their types inferred without reading other files. This enables build tools (esbuild, oxc, swc) to emit .d.ts files in parallel, dramatically speeding up type generation for large monorepos.

TypeScript

// tsconfig.json
{
  "compilerOptions": {
    "isolatedDeclarations": true
  }
}

// ✗ Error under isolatedDeclarations — return type must be explicit
export function formatDate(date: Date) {        // ← inferred return type
  return date.toISOString().split('T')[0];
}

// ✓ Explicit return type — file is self-contained
export function formatDate(date: Date): string {
  return date.toISOString().split('T')[0];
}

// Also requires explicit types on exported variables
export const DEFAULT_TIMEOUT = 5000;           // ✗ — number inferred
export const DEFAULT_TIMEOUT: number = 5000;   // ✓

NOTEisolatedDeclarations is best suited for library authors. Application code can enable it incrementally — the TypeScript CLI will list all files that need annotation.

>Path rewriting for Node.js type-stripping

Node.js 22.6+ can execute TypeScript files natively via --experimental-strip-types. However, Node.js imports must use .js extensions. TypeScript 5.7 introducesrewriteRelativeImportExtensions to automatically rewrite .ts → .js in emitted output.

JSON

// tsconfig.json
{
  "compilerOptions": {
    "rewriteRelativeImportExtensions": true,
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

// source: utils.ts
import { parseDate } from './helpers.ts';   // write .ts in source
//                                            emitted as:
import { parseDate } from './helpers.js';   // ← .js in output

>--noUncheckedSideEffectImports

Side-effect imports like import './polyfill' are silently ignored when the file does not exist. The new --noUncheckedSideEffectImports flag makes TypeScript error on these.

TypeScript

// tsconfig.json
{
  "compilerOptions": {
    "noUncheckedSideEffectImports": true
  }
}

// ✗ Error — './setup' does not exist or is not in the module graph
import './setup';

// ✓ File exists and is resolvable
import './polyfills/css-has';

>Narrowing on awaited type parameters

TypeScript

async function load<T>(promise: Promise<T | null>): Promise<T> {
  const result = await promise;

  // TypeScript 5.7 correctly narrows the awaited type
  if (result === null) {
    throw new Error('No result');
  }

  return result; // T — previously required an explicit cast
}

>Upgrade

bash

npm install typescript@5.7
npx tsc --version  # should print Version 5.7.x

# Enable new flags incrementally in tsconfig.json
# Start with noUncheckedSideEffectImports — lowest friction
# Then isolatedDeclarations if you maintain a library