/typescript-v6

TypeScript 6 Defaults and Configuration Reference

TypeScript 6 changed enough compiler behavior that several assumptions that used to stay implicit often need to become explicit in real projects.

Highest-Impact Upgrade Checks

1. Make types explicit

If a project depends on Node.js globals, a test runner, Workers, or Bun globals, add the exact type packages it needs instead of relying on ambient discovery.

{
  "compilerOptions": {
    "types": ["node", "jest"]
  }
}

This improves both performance and predictability compared with older "load everything from @types" assumptions.

1b. Expect side-effect import checking to be stricter

TS 6 applies stricter checking to side-effect-only imports, so previously ignored path mistakes can start surfacing during normal project work.

2. Make rootDir explicit

If the source tree lives under src/, TypeScript 6+ projects often need this:

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

Without it, some projects can see emitted files shift from dist/index.js to dist/src/index.js.

3. Keep strict deliberate

If the project already uses strict mode, keep it explicit. If the repo truly needs looser semantics during a staged migration, say so explicitly instead of assuming older defaults.

{
  "compilerOptions": {
    "strict": false
  }
}

4. Keep target / lib intentional

Use modern library types only when the project can support them.

{
  "compilerOptions": {
    "target": "es2025",
    "lib": ["es2025", "dom"]
  }
}

Migration Baselines

Bundled web app

{
  "compilerOptions": {
    "target": "es2025",
    "module": "esnext",
    "moduleResolution": "bundler",
    "lib": ["es2025", "dom"],
    "rootDir": "./src",
    "outDir": "./dist",
    "strict": true
  },
  "include": ["src/**/*"]
}

Add a types array here only if the app or its tooling actually needs Node/test/platform globals.

Node package

{
  "compilerOptions": {
    "target": "es2022",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "lib": ["es2022"],
    "rootDir": "./src",
    "outDir": "./dist",
    "types": ["node"],
    "strict": true
  },
  "include": ["src/**/*"]
}

5. Prefer compiler-state inspection before guessing

npx tsc --showConfig
npx tsc --explainFiles

When project behavior looks strange, inspect the effective config and file graph before rewriting source code.

Temporary Escape Hatch

{
  "compilerOptions": {
    "ignoreDeprecations": "6.0"
  }
}

Use this only to buy time while you remove deprecated settings. Do not treat it as a permanent upgrade strategy.