Shared TypeScript configurations

Shared tsconfig.json presets for TypeScript 6 and 7.

| Config | Use for | | --- | --- | | @mkappelhof/ts-config/next.json | Next.js applications | | @mkappelhof/ts-config/react.json | React apps and libraries built with a bundler (Vite, Rsbuild, etc.) | | @mkappelhof/ts-config/node.json | Node.js 24+ services, scripts and CLIs (native ESM) | | @mkappelhof/ts-config/nest.json | NestJS services (CommonJS, legacy decorators) | | @mkappelhof/ts-config/library.json | React libraries built with a bundler that publish type declarations | | @mkappelhof/ts-config/astro.json | Astro sites and apps |

All presets enable strict, noUncheckedIndexedAccess, noImplicitOverride and noFallthroughCasesInSwitch.

Installation

pnpm add -D @mkappelhof/ts-config typescript

Paths in include, exclude, paths and outDir are resolved relative to the config file that declares them. That's why the presets don't set them, and your own tsconfig.json has to.

Next.js

{
  "extends": "@mkappelhof/ts-config/next.json",
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", "**/*.mts", ".next/types/**/*.ts", ".next/dev/types/**/*.ts"],
  "exclude": ["node_modules"]
}

React (bundler)

pnpm add -D @types/react @types/react-dom

{
  "extends": "@mkappelhof/ts-config/react.json",
  "compilerOptions": {
    "types": ["vite/client"]
  },
  "include": ["src"]
}

The preset is type-check only (noEmit). For a React library that publishes type declarations, use library.json instead:

{
  "extends": "@mkappelhof/ts-config/library.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

Node.js

pnpm add -D @types/node

Set "type": "module" in your package.json, then:

{
  "extends": "@mkappelhof/ts-config/node.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

The code only uses erasable TypeScript syntax, so you can run it directly with node src/index.ts or compile it with tsc. Relative imports must include an extension (./util.ts), which is rewritten to .js on emit.

NestJS

pnpm add -D @types/node

{
  "extends": "@mkappelhof/ts-config/nest.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

Unlike the other presets, this one stays on CommonJS and legacy decorators (experimentalDecorators, emitDecoratorMetadata) with erasableSyntaxOnly and verbatimModuleSyntax off, since Nest's constructor-based DI relies on parameter properties and decorator metadata. Build with nest build (or tsc -p tsconfig.build.json).

Astro

{
  "extends": "@mkappelhof/ts-config/astro.json",
  "compilerOptions": {
    "paths": { "@components/*": ["./src/components/*"] }
  },
  "include": [".astro/types.d.ts", "src"],
  "exclude": ["dist"]
}

This preset is self-contained (it doesn't extend Astro's own astro/tsconfigs/* presets), but applies the same strictness as the rest of this package on top of what Astro's strict.json enables: noUncheckedIndexedAccess, noImplicitOverride and noFallthroughCasesInSwitch. Type declarations for astro:* virtual modules and import.meta.env come from a triple-slash reference in your own code, not from this preset:

/// <reference types="astro/client" />

Run astro check to type-check (plain tsc --noEmit won't resolve .astro files).

Breaking changes in 2.0

• next.json, react.json and node.json no longer extend base.json.
• moduleResolution is now bundler (Next.js, React) or NodeNext (Node), instead of the removed node10.
• node.json now targets Node 24 ESM instead of CommonJS.
• react.json and node.json enable verbatimModuleSyntax and erasableSyntaxOnly. Use import type for type-only imports, and replace enums with union types or as const objects.
• noUncheckedIndexedAccess is on in every preset.
• In next.json, the next plugin moved into compilerOptions, where TypeScript actually reads it.

AI agents

The package ships an AGENTS.md that explains the rules these presets enforce. Reference it from your project's AGENTS.md:

- TypeScript: follow `node_modules/@mkappelhof/ts-config/AGENTS.md`