Configure TypeScript

1. Audit current state

Read .claude/stack-profile.md if present: package_manager replaces pnpm below (../_shared/stack-versions.md, "Stack profile"); frontend.framework decides the type-check binary (tsc for React, vue-tsc for Vue).

Inspect the tsconfig that holds the app options. The Vite 8 templates split them: root tsconfig.json is only { "files": [], "references": [...] }, and the options live in tsconfig.app.json.

• Is compilerOptions.strict true? Are noUncheckedIndexedAccess, noImplicitOverride, noUnusedLocals, noUnusedParameters, noFallthroughCasesInSwitch, verbatimModuleSyntax set?
• Is there a paths mapping for @/*? Is baseUrl set? Remove baseUrl: TS 6.0 errors on it (TS5101) and TS 7.0 deletes it (TS5102). paths entries are relative to the tsconfig that declares them, so "./src/*" works without it.
• Does a typecheck script exist? (step 3)

Inspect alias config in whichever exist: vite.config.ts (resolve.alias), vitest.config.ts, .storybook/main.ts, playwright.config.ts.

If every flag is in place and every config has the matching alias, exit early.

2. Decide what to do

• Nothing strict → apply the full set below.
• Strict on but flags missing → add them.
• Flags in place but alias missing somewhere → add it to those configs.
• A flag that produces hundreds of errors on an existing codebase → enable it in its own PR (tsconfig-rules.md, "When to deviate").

3. Update the app tsconfig

Merge into tsconfig.app.json (or tsconfig.json when there is no split):

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "verbatimModuleSyntax": true,
    "paths": { "@/*": ["./src/*"] }
  }
}

The Vite templates already set noUnusedLocals, noUnusedParameters, noFallthroughCasesInSwitch, verbatimModuleSyntax and erasableSyntaxOnly; keep them. Do not add esModuleInterop, allowSyntheticDefaultImports or useDefineForClassFields: tsc --showConfig on TS 6.0 reports them already on for module: esnext and target: es2023. isolatedModules is not needed either; the Vite templates omit it. exactOptionalPropertyTypes is opt-in, not in the default set: see tsconfig-rules.md.

Add a typecheck script. tsc --noEmit at the root checks nothing in the Vite template (files: [], exit 0 on a real error), so the script must build the references:

{ "scripts": { "typecheck": "tsc -b" } }

Vue: "typecheck": "vue-tsc -b". Every other skill in this catalogue verifies with pnpm typecheck.

4. Update vite.config.ts

import { fileURLToPath, URL } from 'node:url';
import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) },
  },
  // ... existing plugins stay
});

Vite 8 can read paths itself with resolve.tsconfigPaths: true, one source of truth instead of two. It is off here because the Vite docs flag a performance cost and it follows include, so an alias in a CSS or .vue file needs matching include entries (docs). The explicit alias costs one line.

5. Vitest (if present)

Vitest 5 inline projects inherit the root config, so a mergeConfig(viteConfig, ...) setup (see path-aliases.md) carries the alias into every project. A standalone vitest.config.ts with no merge needs the alias block from step 4. tests/ needs its own tsconfig so test files are type-checked; configure-test-stack creates it.

6. Storybook (if installed)

Storybook 10's Vite builders (@storybook/react-vite, @storybook/vue3-vite) load the project's vite.config.ts, so the alias is inherited. Add nothing. For another builder, inject the alias in viteFinal.

7. Playwright (if installed)

Playwright resolves paths from the nearest tsconfig itself (verified with 1.64, including through references). Add nothing. Do not add tsconfig-paths or a globalSetup to register aliases: it is dead weight, and the usual snippet (globalSetup: require.resolve(...)) crashes in an ESM project ("type": "module", which the Vite templates set). e2e specs rarely need to import app code; if one does, use a relative import.

8. Verify

pnpm typecheck

Expected: exit 0, no output. Prove the alias with a throwaway file:

// src/__alias-check.ts
import { env } from '@/libs/env'; // any existing module under src/
export const check = env;

Run pnpm typecheck again: still 0 errors. Change the import to @/does-not-exist and confirm it now fails, so you know the check can fail. Delete src/__alias-check.ts.

References

• ./tsconfig-rules.md — every flag with rationale, TS 6/7 notes, the opt-in tier.
• ./path-aliases.md — alias snippets for every config file.
• ../_shared/conventions.md — @/ prefix and the type-check rule.