/shared-tooling-typescript-config

name: shared-tooling-typescript-config
description: TypeScript strict mode configs, TS 5.x+ options (verbatimModuleSyntax, module preserve, moduleDetection force, configDir), path alias sync, specialized configs

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

**(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](examples/core.md) - Full config examples, specialized configs, TS 5.x+ features
• [reference.md](reference.md) - Decision frameworks, anti-patterns, gotchas

---

<philosophy>

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

</philosophy>

---

<patterns>

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](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`/