Instruction file imported from louisbrulenaudet/monorepo-template (.cursor/rules/quality/typescript-config.mdc). Copyright stays with the author.

TypeScript Config Presets

Shared presets live in @repo/typescript-config. Apps and libraries extend a runtime preset - never fork compiler options. The preset JSON is the source of truth for which options are set; read it. This file covers the parts the JSON cannot tell you: which flags change how you must write code, and why two tempting options are deliberately off.

Preset inheritance

flowchart TD
  Strict["strict.json\n(shared strict flags)"]
  Strict --> Library["library.json\nRuntime-neutral libraries"]
  Library --> Workers["workers.json\nthin role alias"]
  Strict --> ViteReact["vite-react.json\nReact + Vite browser"]
  Strict --> ViteNode["vite-node.json\nVite Node tooling"]

Flags that change how you write code

strict.json is more than strict: true. These six will reject ordinary-looking code, so write to them from the start rather than fixing errors afterwards:

Two deliberate omissions

• No preset-level types for Workers. Each Worker app sets compilerOptions.types to ["./worker-configuration.d.ts"], plus "node" when it uses nodejs_compat. Runtime types come from wrangler types, never from the shared preset. Add @cloudflare/workers-types only for a shared library with no wrangler.jsonc.
• isolatedDeclarations is intentionally off. Shared DTOs in @repo/dtos-common use schema-first inference (z.infer<typeof Schema>). Enabling it would demand a hand-written duplicate type on every exported Zod schema, contradicting type-inference.mdc.

Typecheck model (no project references)

Internal packages are Just-in-Time: exports point at source .ts. Typecheck is tsc --noEmit per package, orchestrated by Turborepo with a transit node so packages run in parallel while still invalidating when dependency source changes. Do not add TypeScript Project References, composite, or a root solution tsconfig.json - Turborepo owns the dependency graph.

React SPAs use a split layout (tsconfig.json extends tsconfig.app.json, plus tsconfig.node.json for Vite config) so browser src/** does not inherit Node globals from vite.config.ts. check-types runs both projects with tsc --noEmit -p ....

Test suites are a separate project per package at tests/tsconfig.json, using array extends: the package's own base first, then @repo/typescript-config/tests.json. Keep that path and filename - TypeScript's editor lookup walks up for a file named exactly tsconfig.json, and each package's root config includes src/** only, so a root-level tsconfig.test.json would leave test files in no project (IDE breaks, tsc -p in CI still passes). include arrays replace rather than merge across extends, so a package adding roots (.tsx, vitest.setup.ts, worker-configuration.d.ts) respells the full list with ${configDir} prefixes.

worker-configuration.d.ts is committed, so a fresh clone type-checks with no generate step. Re-run pnpm types and commit only after editing a wrangler.jsonc. Day-to-day CI uses pnpm check-types.

Rules for editing presets

Changing a shared preset is a monorepo-wide breaking change.

1. Extend, don't fork. Always "extends": "@repo/typescript-config/…". Never copy compiler options into an app.
2. Override only what you must - typically compilerOptions.types and include. Prefer package.json "imports" (#/*) over compilerOptions.paths for in-app absolute imports.
3. Keep presets path-agnostic: use ${configDir}; never hardcode paths, and never add paths or imports to a shared preset.
4. Keep runtime concerns in the runtime preset: jsx and DOM lib belong in vite-react.json, never in workers.json.
5. Declare typescript locally: every package running check-types lists "typescript": "catalog:" in devDependencies.
6. Verify repo-wide: run pnpm check-types from the repo root and confirm every app still passes.

Common mistakes

In-app absolute imports

Prefer Node.js subpath imports in the app's package.json over TypeScript compilerOptions.paths (Turborepo TypeScript guide):

{
  "imports": {
    "#/*": [
      "./src/*",
      "./src/*.ts",
      "./src/*.tsx",
      "./src/*/index.ts",
      "./src/*/index.tsx"
    ]
  }
}

import { Button } from "#/components/ui/Button";

Vite resolves package.json "imports" natively - do not mirror aliases in vite.config.ts. Do not add compilerOptions.paths for the same map.

Official documentation

• TSConfig reference
• Cloudflare Workers - TypeScript
• Vite - TypeScript
• Turborepo TypeScript guide