TypeScript 6 Skill

Build, configure, and debug TypeScript 6+ projects with precise compiler guidance and modern module/runtime patterns.

Before You Start

This skill is for real TypeScript 6+ project work: daily development, configuration, debugging, and upgrades.

Known Issues This Skill Prevents

1. Surprise build failures from missing types entries after upgrading
2. Unexpected dist/src/... output because rootDir was never explicit
3. Deprecated moduleResolution node or baseUrl settings surviving into a TS 6 migration
4. Confusion about when to use bundler vs nodenext
5. Overusing ignoreDeprecations: "6.0" as a long-term fix instead of a temporary migration aid
6. Misunderstanding --stableTypeOrdering as a production performance flag instead of a TS 6→7 comparison tool
7. Missing Node/test globals because TS 6+ projects often need explicit types entries
8. New side-effect import errors because TS 6 applies stricter side-effect import checking

Quick Start

Step 1: Make the important options explicit

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

Why this matters: TypeScript 6 changed enough defaults and behaviors that explicit configuration now matters more in everyday work. rootDir and types are two of the most important settings to keep intentional.

Step 2: Pick module resolution deliberately

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

Why this matters: TypeScript 6 deprecates moduleResolution: "node"/"node10". Bundled apps should usually choose bundler, while Node.js packages should usually choose nodenext.

Step 3: Use TS 6-era library typings only when the target/lib/runtime really supports them

const escaped = RegExp.escape('(hello)');

const value = new Map<string, number>().getOrInsert('count', 0);

const tomorrow = Temporal.Now.instant().add({ hours: 24 });

Why this matters: TypeScript 6 can type new platform APIs before every runtime ships them. Distinguish compiler types available from runtime support available.

Step 4: Verify config and resolution before changing code

npx tsc --noEmit
npx tsc --showConfig
npx tsc --explainFiles

Why this matters: TS 6+ projects often fail because the effective config or included file graph is not what the project expects. Validate that first, then refactor.

Critical Rules

Always Do

• Make rootDir explicit when your sources are nested below the tsconfig.json
• Make the types array explicit for Node, test runners, Workers, Bun, or other global type providers when the project relies on those ambient globals
• Prefer moduleResolution: "bundler" for bundled web apps and moduleResolution: "nodenext" for modern Node.js packages
• Treat ignoreDeprecations: "6.0" as a short-term migration escape hatch, not the destination
• Use paths directly instead of relying on deprecated baseUrl
• Make types explicit when the project truly depends on Node, test, Worker, or Bun globals
• Treat side-effect imports as intentionally checked and fix their paths deliberately
• Verify runtime support before recommending Temporal, getOrInsert, or RegExp.escape
• Use --stableTypeOrdering only when comparing TS 6 and TS 7 behavior or investigating ordering-sensitive issues
• Use satisfies, exhaustive never checks, and assertion functions when TS 6+ code exposes type ambiguity that should be made explicit
• Re-run tsc --noEmit after config changes and again after type-pattern refactors

Never Do

• Never recommend deprecated moduleResolution: "node" / "node10" as the forward-looking path
• Never recommend removed moduleResolution: "classic" as a fallback path
• Never leave types implicit if a project depends on @types/node, test globals, or platform globals
• Never assume ignoreDeprecations: "6.0" will keep working in TypeScript 7
• Never present TS 7 preview context as if it were already the default compiler runtime
• Never imply that TypeScript types guarantee runtime availability for new ECMAScript APIs
• Never import pre-TS 6 tsconfig advice that still uses skipDefaultLibCheck, downlevelIteration, or old AMD/UMD/SystemJS examples

Common Mistakes

Wrong - relying on pre-TS 6 ambient type loading:

{
  "compilerOptions": {
    "outDir": "./dist"
  }
}

Correct - declare what global types the project actually needs:

{
  "compilerOptions": {
    "outDir": "./dist",
    "types": ["node"]
  }
}

Why: In TS 6+, explicit types improves performance and predictability when the project depends on ambient globals.

Wrong - keep deprecated path alias setup unchanged:

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@app/*": ["app/*"]
    }
  }
}

Correct - inline the source prefix in paths:

{
  "compilerOptions": {
    "paths": {
      "@app/*": ["./src/app/*"]
    }
  }
}

Why: baseUrl is deprecated in TS 6. The forward-looking setup is direct paths entries.

Wrong - type widening hides the real config contract:

const compilerMode = {
  moduleResolution: 'bundler',
  strict: true,
};

Correct - keep literals checked without widening:

const compilerMode = {
  moduleResolution: 'bundler',
  strict: true,
} satisfies {
  moduleResolution: 'bundler' | 'nodenext';
  strict: boolean;
};

Why: satisfies is not new in TS 6, but it is one of the cleanest ways to make config and option objects precise without losing inference.

Wrong - union handling silently misses a new case:

type ResolutionMode = 'bundler' | 'nodenext' | 'preserve';

function describeMode(mode: ResolutionMode) {
  if (mode === 'bundler') return 'bundled app';
  return 'node-style runtime';
}

Correct - exhaustive union handling:

type ResolutionMode = 'bundler' | 'nodenext' | 'preserve';

function describeMode(mode: ResolutionMode) {
  switch (mode) {
    case 'bundler':
      return 'bundled app';
    case 'nodenext':
      return 'node-style runtime';
    case 'preserve':
      return 'mixed emit strategy';
    default: {
      const exhaustive: never = mode;
      return exhaustive;
    }
  }
}

Why: TypeScript 6+ projects often rely on unions for config, platform, and runtime state. Exhaustive never checks make missing cases obvious.

Wrong - use stableTypeOrdering as a normal build flag:

tsc --stableTypeOrdering --build

Correct - use it only for comparison/debugging:

tsc --noEmit --stableTypeOrdering

Why: The flag exists to reduce TS 6 vs TS 7 output noise. It can meaningfully slow type-checking and is not intended as a permanent default.

Known Issues Prevention

Bundled Resources

References

• Dedicated TS 6 migration guide → references/migration-v6-reference.md
• Defaults and configuration behavior → references/defaults-migration-reference.md
• Deprecations and replacements → references/deprecations-reference.md
• Module resolution and #/ imports → references/module-resolution-imports-reference.md
• New library types and APIs → references/stdlib-types-reference.md
• Verification workflow and diagnostics → references/workflow-diagnostics-reference.md
• Type-safe patterns for TS 6+ code → references/type-patterns-reference.md
• stableTypeOrdering and TS 7 context → references/stable-ordering-ts7-reference.md
• Reference index → references/README.md

Configuration Reference

Bundled application baseline

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

Key settings:

• rootDir: Prevents accidental dist/src/... nesting
• types: Add it explicitly only when the project actually depends on Node/test/platform globals
• moduleResolution: "bundler": Best fit for Vite/esbuild/Rollup/Webpack-style app builds
• target: "es2025" / lib: ["es2025", ...]: Gives access to TS 6-era built-in types such as RegExp.escape

Node package baseline

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

Key settings:

• nodenext: Use when the package's runtime semantics should follow modern Node.js ESM/CJS rules
• Explicit .js import specifiers and package.json module settings still matter; TS 6 does not remove that responsibility

Project Structure

my-ts-project/
├── src/
├── dist/
├── package.json
└── tsconfig.json

Why this matters: TS 6 rewards explicit, boring project structure. Most upgrade pain comes from old implicit config behavior, not from source code syntax.

Common Patterns

Direct paths migration

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Use this instead of keeping deprecated baseUrl around.

#/ subpath imports for package-internal aliases

{
  "name": "my-package",
  "type": "module",
  "imports": {
    "#/*": "./dist/*"
  }
}

import * as utils from '#/utils.js';

Use this when your package/runtime already supports Node's imports field and you want package-native aliases instead of bundler-only conventions. Keep the exact mapping aligned with the files the package actually ships.

Temporary migration shield

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

Use this only long enough to unblock the migration. Plan to remove it before TS 7.

Monorepo/project-reference check

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "isolatedDeclarations": true,
    "rootDir": "./src",
    "outDir": "./dist"
  }
}

Use this when packages emit .d.ts files or participate in project references. isolatedDeclarations is not TS 6-exclusive, but it fits the stricter, more explicit TS 6+ workflow well.

Verification Workflow

npx tsc --noEmit
npx tsc --showConfig
npx tsc --explainFiles
npx tsc --traceResolution

When to use each command:

• --noEmit: First-pass health check after config or type changes
• --showConfig: Confirm the effective merged config before debugging phantom settings
• --explainFiles: Understand why a file is in the program or why a file graph changed
• --traceResolution: Debug paths, package exports, types, or #/ import resolution

Troubleshooting

"Cannot find name 'process'" / "Cannot find name 'describe'"

Add the appropriate types entries and install the matching @types/* package if needed.

Output path changed unexpectedly

Set rootDir explicitly. This is one of the most common TS 6 upgrade regressions.

Deprecated option warnings keep appearing

Migrate away from deprecated settings; use ignoreDeprecations: "6.0" only while the real replacement work is still in progress.

New side-effect import errors appear in TS 6+

Inspect the import path and whether the file is intended as a side-effect-only module. TS 6 applies stricter checking here, so old typos or vague side-effect imports can surface now.

RegExp.escape / Temporal / getOrInsert compile but fail in production

Check runtime support. TS 6 can expose types before every target environment implements the runtime API.

Setup Checklist

• rootDir is explicit if source files live below the tsconfig.json
• types is explicit for Node, tests, Workers, Bun, or other ambient platforms
• moduleResolution is bundler or nodenext, not deprecated node / node10
• Removed classic resolution, skipDefaultLibCheck, and downlevelIteration are not lingering in copied config
• Deprecated baseUrl / downlevelIteration / ES5-era settings are removed or scheduled for removal
• tsc --showConfig and tsc --explainFiles were used if the upgrade behavior is still surprising
• ignoreDeprecations: "6.0" is temporary and tracked
• New TS 6 APIs are validated against actual runtime support
• --stableTypeOrdering is only used for migration comparisons, not normal builds

Official Documentation

• TypeScript 6.0 Release Notes
• TypeScript Handbook
• TSConfig Reference
• Compiler Options Reference
• Choosing Compiler Options