shared-tooling-typescript-config

TypeScript Configuration Patterns

Quick Guide: Shared TypeScript strict config in packages/typescript-config/. Enable strict: true plus noUncheckedIndexedAccess, exactOptionalPropertyTypes, noImplicitOverride. Use modern module settings: module: "preserve", moduleResolution: "bundler", verbatimModuleSyntax: true, moduleDetection: "force". Use ${configDir} (TS 5.5+) for portable paths. Sync path aliases between tsconfig and your build tool.

---

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST enable TypeScript strict mode (strict: true) in ALL tsconfig.json files - non-negotiable)

(You MUST use verbatimModuleSyntax: true to enforce explicit import type - replaces deprecated importsNotUsedAsValues)

(You MUST use shared config pattern (packages/typescript-config/) in monorepos - never duplicate configs per package)

(You MUST sync path aliases between tsconfig.json and your build tool - mismatches cause import resolution failures)

(You MUST use modern module settings: module: "preserve", moduleResolution: "bundler" for bundler-based projects)

</critical_requirements>

---

Auto-detection: TypeScript config, tsconfig.json, tsconfig, strict mode, noUncheckedIndexedAccess, exactOptionalPropertyTypes, verbatimModuleSyntax, moduleDetection force, module preserve, moduleResolution bundler, configDir, path aliases, typescript-config, shared config, noImplicitOverride, isolatedDeclarations, erasableSyntaxOnly, import defer

When to use:

• Setting up TypeScript strict mode in new or existing projects
• Creating shared tsconfig patterns for monorepo consistency
• Configuring TS 5.x+ modern module settings (preserve, bundler, verbatimModuleSyntax)
• Syncing path aliases between tsconfig and your build tool
• Creating specialized configs (React, Node.js, library publishing)
• Migrating from deprecated TypeScript options
• Evaluating new TS features (isolatedDeclarations, erasableSyntaxOnly, configDir, import defer)

When NOT to use:

• Runtime TypeScript code patterns (see language/framework skills)
• Linter configuration (separate skill)
• Build tool configuration (separate skill) - but DO keep path alias sync guidance here
• Daily coding conventions like naming and imports (see CLAUDE.md)

Key patterns covered:

• Shared strict config base with monorepo extension pattern
• Modern module settings (TS 5.x+: preserve, bundler, verbatimModuleSyntax, moduleDetection)
• ${configDir} template variable for portable shared configs (TS 5.5+)
• Path alias sync between tsconfig and build tools
• Specialized configs (react.json, node.json, library.json)
• isolatedDeclarations for parallel build support (TS 5.5+)
• erasableSyntaxOnly for Node.js direct execution (TS 5.8+)
• import defer for deferred module evaluation (TS 5.9+)
• TypeScript 6.0 new defaults and deprecations

Detailed resources:

• examples/core.md - Full config examples, specialized configs, TS 5.x+ features
• reference.md - Decision frameworks, anti-patterns, gotchas

---

Philosophy

TypeScript configuration should be strict by default, shared across packages, and forward-compatible. Every project starts with the strictest settings. Shared configs prevent drift. Modern module settings align with bundler-based workflows.

Core principles:

1. Strict by default - strict: true plus noUncheckedIndexedAccess, exactOptionalPropertyTypes, noImplicitOverride
2. Share, don't duplicate - Monorepo configs extend a shared base; standalone projects use the same strict options
3. Modern module mode - module: "preserve" + moduleResolution: "bundler" for bundler projects; "node18"/"node20" for Node.js
4. Path alias parity - Aliases must exist in both tsconfig AND the build tool

---

Core Patterns

Pattern 1: Shared Strict Config Base

All apps and packages extend a shared strict base. The base config lives in packages/typescript-config/ (monorepo) or is inlined in a standalone project.

// packages/typescript-config/base.json (abbreviated)
{
  "compilerOptions": {
    "strict": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "module": "preserve",
    "moduleResolution": "bundler",
    "verbatimModuleSyntax": true
  }
}

Consumer configs extend the shared base and only add what differs (e.g. paths).

Why good: Single source of truth for strict settings, all packages get the same safety guarantees, consumers only add what differs

See examples/core.md for full base config, consumer configs, and specialized configs (react.json, node.json, library.json).

---

Pattern 2: Modern Module Settings (TS 5.x+)

verbatimModuleSyntax (TS 5.0+)

Enforces explicit import type for type-only imports. Replaces deprecated importsNotUsedAsValues and preserveValueImports.

// With verbatimModuleSyntax: true

// Good - explicit type import
import type { User } from "./types";
import { createUser } from "./api";

// Bad - type imported as value (errors with verbatimModuleSyntax)
import { User, createUser } from "./api";

module: "preserve" (TS 5.4+)

Preserves import/export syntax as-is. TypeScript only type-checks; the bundler handles module output.

When to use: Bundler-based projects where TypeScript does NOT emit JavaScript (noEmit: true)

When not to use: Node.js packages that emit CJS/ESM directly -- use module: "node18" or "node20" instead

moduleDetection: "force" (TS 5.0+)

Forces all files to be treated as modules, even without import/export. Prevents unexpected global scope pollution.

---

Pattern 3: ${configDir} Template Variable (TS 5.5+)

Makes shared configs portable. ${configDir} resolves to the directory of the leaf config (the one that extends), not the base.

// packages/typescript-config/base.json
{
  "compilerOptions": {
    "outDir": "${configDir}/dist",
    "rootDir": "${configDir}/src"
  },
  "include": ["${configDir}/src"]
}

Why good: Consumers don't need to override outDir, rootDir, or include -- paths resolve relative to their own directory

Gotcha: Without ${configDir}, relative paths like "./dist" resolve from the base config's location (packages/typescript-config/), not the consuming package.

---

Pattern 4: Path Alias Sync

Path aliases must be configured in BOTH tsconfig.json AND your build tool. A mismatch causes either TypeScript errors or build-time import resolution failures.

// tsconfig.json -- paths here for TypeScript type checking
{ "compilerOptions": { "paths": { "@/*": ["./src/*"] } } }

// Build tool config -- SAME aliases for bundler resolution
// resolve: { alias: { "@": path.resolve(__dirname, "./src") } }

Gotcha: Forgetting to sync causes "module not found" errors. TypeScript resolves fine but the bundler fails (or vice versa). When adding a new alias, always update BOTH files.

See examples/core.md for full tsconfig + build tool config examples.

---

Pattern 5: isolatedDeclarations (TS 5.5+)

Requires explicit type annotations on all exports. Enables parallel .d.ts generation by external tools (oxc, swc).

// With isolatedDeclarations: true

// Good - explicit return type on export
export function getUser(id: string): User {
  return { id, name: "John" };
}

// Bad - inferred return type (will error)
export function getUser(id: string) {
  return { id, name: "John" };
}

When to use: Large monorepos publishing library packages where parallel .d.ts generation speeds up builds

When not to use: Application code that is never consumed as a library (adds verbosity for no benefit)

---

Pattern 6: erasableSyntaxOnly (TS 5.8+)

Prohibits TypeScript-specific constructs that have runtime behavior (enums, namespaces, parameter properties). Ensures compatibility with Node.js --experimental-strip-types for direct TS execution.

Blocked constructs: enum, const enum, runtime namespace, parameter properties (constructor(public name: string))

Allowed constructs: type, interface, type-only imports -- anything that can be erased without changing runtime behavior

When to use: Projects using Node.js direct TS execution, or targeting the types-only philosophy

When not to use: Projects that rely heavily on enums, namespaces, or parameter properties

See examples/core.md for full good/bad code examples.

---

Pattern 7: import defer (TS 5.9+)

Deferred module evaluation -- the module loads but doesn't execute until an export is accessed. Only works with namespace imports under --module preserve or esnext.

import * as analytics from "./heavy-analytics.js";

// Module is loaded but NOT executed yet
if (needsAnalytics) {
  analytics.track("event"); // Module executes here on first access
}

When to use: Improving startup performance for conditionally-loaded heavy modules

Limitation: Named imports and default imports are not supported with import defer -- only namespace syntax (import defer * as ...)

---

Pattern 8: TypeScript 6.0 New Defaults

TS 6.0 (February 2026) changes several defaults. If your config already follows the patterns above, most changes are transparent.

Option	Old Default	TS 6.0 Default
strict	false	true
module	commonjs	esnext
target	es3	es2025
rootDir	inferred	. (current dir)
types	auto-discover @types/*	[] (explicit only)
noUncheckedSideEffectImports	false	true
libReplacement	true	false

Action required: Set "types": ["node"] (or relevant packages) explicitly after upgrading to TS 6.0 -- the auto-discovery of @types/* is gone.

Deprecated in TS 6.0 (removed in TS 7.0):

• target: "es5", moduleResolution: "node" (node10), module: "amd"|"umd"|"systemjs"|"none"
• esModuleInterop: false, --baseUrl as module resolution root, --outFile

Use "ignoreDeprecations": "6.0" during migration to suppress warnings.

See examples/core.md for full TS 6.0 defaults table and deprecation details.

---

Pattern 9: NoInfer Utility Type (TS 5.4+)

Prevents TypeScript from inferring a type from a specific position in generic functions.

// Good - NoInfer ensures initial must be from states array
declare function createFSM<TState extends string>(config: {
  initial: NoInfer<TState>;
  states: TState[];
}): void;

createFSM({
  initial: "invalid", // Error: "invalid" not in states
  states: ["open", "closed"],
});

Why good: TypeScript infers TState from states only; initial must match without widening the union

When to use: Generic functions where one parameter should constrain another, not expand the inferred type

---

<decision_framework>

Decision Framework

Module Settings Selection

What module/moduleResolution to use?
├─ Bundler-based project (TypeScript does NOT emit JS)?
│   └─ YES -> module: "preserve", moduleResolution: "bundler"
├─ Node.js package (direct execution)?
│   ├─ Node 20+? -> module: "node20" (TS 5.9+, stable)
│   └─ Node 18+? -> module: "node18" (TS 5.8+)
└─ Library consumed by both bundlers and Node?
    └─ module: "nodenext" (most compatible)

Target Selection

What target to use?
├─ Bundler-based project? -> target: "ES2022" (stable, well-supported)
├─ Node.js 18+? -> target: "ES2022"
├─ Node.js 20+? -> target: "ES2023"
└─ TS 6.0+ project? -> target: "es2025" (new default)

New Feature Adoption

isolatedDeclarations?
├─ Publishing library packages in large monorepo? -> Enable
├─ Application code only? -> Skip (adds verbosity for no benefit)
└─ Using oxc or swc for builds? -> Enable (these tools benefit most)

erasableSyntaxOnly?
├─ Using Node.js --experimental-strip-types? -> Enable (required)
├─ Project uses enums extensively? -> Skip (migration cost too high)
└─ Standard bundler project? -> Optional (nice-to-have)

See reference.md for additional decision frameworks (shared vs local config, TS 6.0 migration).

</decision_framework>

---

<red_flags>

RED FLAGS

High Priority Issues:

• Disabling TypeScript strict mode (strict: false) -- allows implicit any and null bugs across the project
• Missing verbatimModuleSyntax: true -- type imports may or may not be elided depending on transpiler
• Not using shared configs in monorepo -- configs drift, creating inconsistent safety levels across packages
• Using deprecated importsNotUsedAsValues or preserveValueImports -- replaced by verbatimModuleSyntax since TS 5.0

Medium Priority Issues:

• Path aliases in tsconfig but not in build tool (or vice versa) -- causes import resolution failures
• Using deprecated moduleResolution: "node" (node10) instead of "bundler" or "node18" -- deprecated in TS 6.0
• Using deprecated target: "ES3" or "ES5" -- deprecated in TS 6.0, removed in TS 7.0
• Duplicated config per package instead of extending shared base

Gotchas & Edge Cases:

• ${configDir} resolves to the directory of the leaf config (the one that uses extends), not the base config
• verbatimModuleSyntax requires ALL type-only imports to use import type -- mixed imports like import { Type, value } error if Type is type-only. Use inline syntax: import { type Type, value }
• exactOptionalPropertyTypes means { key?: string } does NOT accept { key: undefined } -- only omission or string
• noUncheckedIndexedAccess adds | undefined to ALL index signatures, including arrays -- use for...of or guard with if
• module: "preserve" only works with noEmit: true or emitDeclarationOnly: true
• TS 6.0 changes types default to [] -- @types/node, @types/react etc. must be explicitly listed after upgrade
• import defer only supports namespace syntax (import defer * as ...), not named or default imports

</red_flags>

---

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST enable TypeScript strict mode (strict: true) in ALL tsconfig.json files - non-negotiable)

(You MUST use verbatimModuleSyntax: true to enforce explicit import type - replaces deprecated importsNotUsedAsValues)

(You MUST use shared config pattern (packages/typescript-config/) in monorepos - never duplicate configs per package)

(You MUST sync path aliases between tsconfig.json and your build tool - mismatches cause import resolution failures)

(You MUST use modern module settings: module: "preserve", moduleResolution: "bundler" for bundler-based projects)

Failure to follow these rules will cause type-safety gaps, inconsistent configs, and import resolution failures.

</critical_reminders>