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.

Metric	Without Skill	With Skill
Upgrade Investigation Time	~90 min	~30 min
Common tsconfig Regressions	5+	0-1
Token Usage	High (manual diffing)	Low (release-note-grounded guidance)

Known Issues This Skill Prevents

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

Quick Start

Step 1: Make the important options explicit

json

{
  "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

json

{
  "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

bash

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:

json

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

Correct - declare what global types the project actually needs:

json

{
  "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:

json

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

Correct - inline the source prefix in
paths
:

json

{
  "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:

bash

tsc --stableTypeOrdering --build

Correct - use it only for comparison/debugging:

bash

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

Issue	Root Cause	Solution
`process` / `describe` / `fs` suddenly missing	The project relied on ambient type discovery that is no longer safe to assume during TS 6 migration work	Add explicit entries like `"types": ["node", "jest"]`
Output moves to `dist/src/...`	The project relied on inferred source-root behavior that TS 6 migration work often needs to replace with explicit config	Set `rootDir` explicitly, usually `./src`
Upgrade warnings explode	Deprecated module resolution or emit-era options survived from older configs	Migrate to `bundler` or `nodenext` ; remove deprecated options
Side-effect imports suddenly error	Side-effect import checking is stricter in TS 6+ projects	Fix typos, add explicit files, or tighten import paths intentionally
`#/` imports do not resolve	Runtime or resolution mode does not match TS 6 support requirements	Use Node 20+ support with `moduleResolution: "bundler"` or `"nodenext"`
New ES APIs compile but fail at runtime	TS lib types are present, runtime support is not	Verify runtime compatibility and polyfill strategy separately
Type ordering changes create noisy diffs	TS 6/TS 7 ordering differs during migration experiments	Use `--stableTypeOrdering` temporarily

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

json

{
  "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

json

{
  "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

json

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

Use this instead of keeping deprecated

baseUrl

around.

#/

subpath imports for package-internal aliases

json

{
  "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

json

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

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

Monorepo/project-reference check

json

{
  "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

bash

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

bundler

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

typescript-v6

NPX Install

Tags

SKILL.md Content

TypeScript 6 Skill

Before You Start

Known Issues This Skill Prevents

Quick Start

Step 1: Make the important options explicit

Step 2: Pick module resolution deliberately

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

Step 4: Verify config and resolution before changing code

Critical Rules

Always Do

Never Do

Common Mistakes

Known Issues Prevention

Bundled Resources

References

Configuration Reference

Bundled application baseline

Node package baseline

Project Structure

Common Patterns

Direct
`paths`
migration

`#/`
subpath imports for package-internal aliases

Temporary migration shield

Monorepo/project-reference check

Verification Workflow

Troubleshooting

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

Output path changed unexpectedly

Deprecated option warnings keep appearing

New side-effect import errors appear in TS 6+

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

Setup Checklist

Official Documentation

typescript-v6

NPX Install

Tags

SKILL.md Content

TypeScript 6 Skill

Before You Start

Known Issues This Skill Prevents

Quick Start

Step 1: Make the important options explicit

Step 2: Pick module resolution deliberately

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

Step 4: Verify config and resolution before changing code

Critical Rules

Always Do

Never Do

Common Mistakes

Known Issues Prevention

Bundled Resources

References

Configuration Reference

Bundled application baseline

Node package baseline

Project Structure

Common Patterns

Direct paths migration

#/ subpath imports for package-internal aliases

Temporary migration shield

Monorepo/project-reference check

Verification Workflow

Troubleshooting

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

Output path changed unexpectedly

Deprecated option warnings keep appearing

New side-effect import errors appear in TS 6+

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

Setup Checklist

Official Documentation

Direct
`paths`
migration

`#/`
subpath imports for package-internal aliases

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