@mkappelhof/ts-config 1.0.6 → 2.1.0

package/.turbo/turbo-build.log

@@ -0,0 +1,13 @@
+
+> @mkappelhof/ts-config@1.0.7 build /Users/mauricekappelhof/Dev/frontend-tools/packages/ts-config
+> rollup -c
+
+
+./base.json → ./dist/base.json...
+(!) Mixing named and default exports
+https://rollupjs.org/configuration-options/#output-exports
+The following entry modules are using named and default exports together:
+base.json
+
+Consumers of your bundle will have to use chunk.default to access their default export, which may not be what you want. Use `output.exports: "named"` to disable this warning.
+created ./dist/base.json in 22ms

package/AGENTS.md

@@ -0,0 +1,68 @@
+# @mkappelhof/ts-config — agent instructions
+
+This project's `tsconfig.json` extends a shared config from `@mkappelhof/ts-config`. Write code that type-checks under these settings, and do not loosen them.
+
+## Which config is in use
+
+Check `extends` in the project's `tsconfig.json`:
+
+| Config | For | Module system |
+| --- | --- | --- |
+| `@mkappelhof/ts-config/next.json` | Next.js apps | ESM, bundler resolution, type-check only (`noEmit`) |
+| `@mkappelhof/ts-config/react.json` | React apps and libraries built with a bundler (Vite, etc.) | ESM, bundler resolution, type-check only (`noEmit`) |
+| `@mkappelhof/ts-config/node.json` | Node.js 24+ services, scripts and CLIs | Native Node ESM (`NodeNext`) |
+| `@mkappelhof/ts-config/nest.json` | NestJS services | CommonJS, legacy decorators (`experimentalDecorators`, `emitDecoratorMetadata`) |
+| `@mkappelhof/ts-config/library.json` | React libraries built with a bundler that publish type declarations | ESM, bundler resolution, declaration emit only (`emitDeclarationOnly`) |
+| `@mkappelhof/ts-config/astro.json` | Astro sites and apps | ESM, bundler resolution, type-check only (`noEmit`), `jsx: "preserve"` |
+
+## Rules that apply to every config
+
+- **`strict` is on, plus `noUncheckedIndexedAccess`.** Indexing an array or record returns `T | undefined`. Narrow it (`if (item)`, `?.`, `??`) instead of using `!` or `as`.
+- **`noImplicitOverride`.** Mark overridden class members with `override`.
+- **`noFallthroughCasesInSwitch`.** Every non-empty `case` must `break`, `return` or `throw`.
+- Path aliases are defined in `compilerOptions.paths` in the project's own `tsconfig.json`, never in these presets. Check there before assuming an import needs a relative path.
+- Ambient types beyond the preset's `lib` (e.g. `chrome` for a browser extension, or a test runner's globals) go in `compilerOptions.types` in the project's own `tsconfig.json`.
+- Do not add `// @ts-ignore`. If you must suppress an error, use `// @ts-expect-error` with a reason.
+- Do not change the compiler options in the project's `tsconfig.json` to make an error go away. Fix the code.
+
+## next.json
+
+- JSX uses the automatic runtime (`react-jsx`). Do not `import React` just for JSX.
+- Imports have no file extensions (`import { x } from './util'`).
+- Keep `next-env.d.ts` and the `.next/types/**/*.ts` entries in `include`. Next.js generates them.
+- Run `pnpm tsc --noEmit` (or `pnpm next build`) to type-check.
+
+## react.json
+
+- `verbatimModuleSyntax` is on. Import types with `import type { Foo } from './foo'` (or the inline form `import { type Foo }`).
+- `erasableSyntaxOnly` is on. Do not use `enum`, `namespace`, parameter properties (`constructor(private x: string)`) or `import x = require()`. Use union types or `as const` objects instead of enums.
+- JSX uses the automatic runtime (`react-jsx`). Do not `import React` just for JSX.
+- `.ts` / `.tsx` extensions in imports are allowed but not required.
+
+## library.json
+
+- Extends `react.json`, so the same `verbatimModuleSyntax` and `erasableSyntaxOnly` rules apply.
+- `noEmit` is off and `emitDeclarationOnly` is on: `tsc` only ever emits `.d.ts` files, never `.js`. Build the JS with your bundler, and run `tsc` (or `tsc --build`) separately to emit declarations.
+- Set `outDir` and `rootDir` in the project's own `tsconfig.json`.
+
+## node.json
+
+- The project must have `"type": "module"` in `package.json`. Use `import`/`export` and never `require`/`module.exports`.
+- **Relative imports must include the file extension.** Write `import { x } from './util.ts'` (or `./util.js`). Both resolve, and `.ts` is rewritten to `.js` on emit.
+- `verbatimModuleSyntax` and `erasableSyntaxOnly` are on, same rules as `react.json`. Because of the latter, the source can run directly with `node file.ts`.
+- Top-level `await` is allowed.
+- `@types/node` must be installed. It is the only ambient types package loaded (`"types": ["node"]`); add others to `types` in the project's `tsconfig.json`.
+
+## nest.json
+
+- CommonJS, not ESM: `module`/`moduleResolution` are `commonjs`/`node`. Use `require`/`module.exports` semantics via `import`/`export` as Nest's CLI generates them; there's no `"type": "module"` requirement and no file-extension-in-import rule.
+- `experimentalDecorators` and `emitDecoratorMetadata` are on, and `erasableSyntaxOnly`/`verbatimModuleSyntax` are off (unlike every other preset in this package). Parameter properties (`constructor(private readonly foo: FooService) {}`) and decorators (`@Injectable()`, `@Controller()`, etc.) are expected and fine to use here — this is the one preset where that's true.
+- Run `nest build` (or `tsc -p tsconfig.build.json` if the project has one) to compile; don't switch the project to `tsc --noEmit`-only workflows.
+
+## astro.json
+
+- `jsx` is `"preserve"`, not `"react-jsx"`. `.astro` files are their own syntax, compiled by the Astro compiler, not `tsc`; this setting only matters for `.tsx` islands (e.g. from `@astrojs/react`), and Astro's Vite plugin handles their actual JSX transform regardless of this setting.
+- `verbatimModuleSyntax` and `erasableSyntaxOnly` are on, same rules as `react.json`/`node.json`: use `import type`, and no `enum`, `namespace` or parameter properties.
+- Ambient types for `astro:*` virtual modules and `import.meta.env` come from `/// <reference types="astro/client" />` in your own code (commonly in `src/env.d.ts`), not from this preset.
+- This preset does not `extend` Astro's own `astro/tsconfigs/strict.json` — it's self-contained, with the equivalent compiler options plus this package's usual `noUncheckedIndexedAccess`, `noImplicitOverride` and `noFallthroughCasesInSwitch` (Astro's `strict.json` alone does not enable these three; `strictest.json` does, but also turns on other checks this package doesn't standardize on, such as `noUnusedLocals`).
+- Use `astro check` to type-check, not bare `tsc --noEmit` — only the Astro CLI resolves `.astro` files.

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # @mkappelhof/ts-config
 
+## 2.1.0
+
+### Minor Changes
+
+- 3c4c6b4: Add `nest.json` preset for NestJS services: CommonJS, `experimentalDecorators`/`emitDecoratorMetadata` on, `erasableSyntaxOnly`/`verbatimModuleSyntax` off so parameter properties and decorator-based DI work.
+
+## 2.0.1
+
+### Patch Changes
+
+- eb2577f: Add new configs
+
+## 2.0.0
+
+### Major Changes
+
+- 9665a73: Modernise `next.json`, `react.json` and `node.json` for TypeScript 6/7, Next.js 16 and Node 24. They no longer extend `base.json`; use `bundler`/`NodeNext` module resolution; and enable `noUncheckedIndexedAccess`. `react.json` and `node.json` also enable `verbatimModuleSyntax` and `erasableSyntaxOnly`, and `node.json` targets native ESM. Adds `AGENTS.md`.
+  
+  Also:
+  
+  - Adds a `library.json` preset (extends `react.json`) for React libraries that publish type declarations, replacing the manual `compilerOptions` override documented in the README.
+  - Removes the Rollup build. `main` already pointed at the source `base.json`, and nothing consumed the `dist/` output it produced.
+
+### Minor Changes
+
+- 1eb73de: Add an `astro.json` preset to `@mkappelhof/ts-config`, pulled from how a real Astro site configures
+  TypeScript: Astro's own `strict.json` base plus this package's usual `noUncheckedIndexedAccess`,
+  `noImplicitOverride` and `noFallthroughCasesInSwitch`.
+  
+  Also documents pinning Biome's `astro` lint domain in `@mkappelhof/biome-config`'s README, alongside
+  the existing `react`/`next`/`test` domain guidance.
+
+### Patch Changes
+
+- 58ff254: Pull in live configuration learnings from a real project:
+  
+  - `@mkappelhof/biome-config`: enable `html.experimentalFullSupportEnabled`, and document in the
+    `AGENTS.md`/README how to pair this config with `@mkappelhof/stylelint-config` without the two
+    tools overlapping on the same files.
+  - `@mkappelhof/ts-config`: document in `AGENTS.md` that `react.json` projects define path aliases
+    and any extra ambient `types` (e.g. browser-extension globals) in their own `tsconfig.json`.
+  
+  Also adds a new `@mkappelhof/stylelint-config` package (Stylelint config for CSS/SCSS, built on
+  `stylelint-config-standard` + `stylelint-config-recommended-scss`), for projects that pair Biome
+  with Stylelint instead of relying on Biome for styles.
+
+## 1.0.7
+
+### Patch Changes
+
+- 7a413a3: Add deployment to Github
+
 ## 1.0.6
 
 ### Patch Changes

package/README.md

@@ -1,15 +1,146 @@
-# Shared Typescript configurations
+# 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
 
-Add the package as a local dev dependency
+```sh
+pnpm add -D @mkappelhof/ts-config typescript
+```
 
-`yarn add @mkappelhof/ts-config`
+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.
 
-Then create a `.tsconfig.json` config file with the following content:
+### Next.js
 
 ```JSON
 {
   "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)
+
+```sh
+pnpm add -D @types/react @types/react-dom
+```
+
+```JSON
+{
+  "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:
+
+```JSON
+{
+  "extends": "@mkappelhof/ts-config/library.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
+```
+
+### Node.js
+
+```sh
+pnpm add -D @types/node
+```
+
+Set `"type": "module"` in your `package.json`, then:
+
+```JSON
+{
+  "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
+
+```sh
+pnpm add -D @types/node
+```
+
+```JSON
+{
+  "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
+
+```JSON
+{
+  "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:
+
+```ts
+/// <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 `enum`s 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`:
+
+```md
+- TypeScript: follow `node_modules/@mkappelhof/ts-config/AGENTS.md`
+```

package/astro.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://www.schemastore.org/tsconfig",
+  "display": "Astro",
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": [
+      "DOM",
+      "DOM.Iterable",
+      "ESNext"
+    ],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "jsx": "preserve",
+    "allowJs": true,
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "erasableSyntaxOnly": true,
+    "noEmit": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}

package/base.json

@@ -19,5 +19,7 @@
     "skipLibCheck": true,
     "strict": true
   },
-  "exclude": ["node_modules"]
-}
+  "exclude": [
+    "node_modules"
+  ]
+}

package/library.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://www.schemastore.org/tsconfig",
+  "display": "React Library",
+  "extends": "./react.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "allowImportingTsExtensions": false
+  }
+}

package/nest.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://www.schemastore.org/tsconfig",
+  "display": "NestJS",
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": [
+      "ES2023"
+    ],
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "moduleDetection": "force",
+    "types": [
+      "node"
+    ],
+    "resolveJsonModule": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true
+  }
+}

package/next.json

@@ -1,17 +1,31 @@
 {
-  "$schema": "https://json.schemastore.org/tsconfig",
-  "display": "React Library",
-  "extends": "./base.json",
+  "$schema": "https://www.schemastore.org/tsconfig",
+  "display": "Next.js",
   "compilerOptions": {
-    "incremental": true,
-    "jsx": "preserve",
-    "lib": ["dom", "ES2015"],
+    "target": "ES2022",
+    "lib": [
+      "DOM",
+      "DOM.Iterable",
+      "ESNext"
+    ],
     "module": "ESNext",
-    "target": "es6"
-  },
-  "plugins": [
-    {
-      "name": "next"
-    }
-  ]
-}
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "incremental": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  }
+}

package/node.json

@@ -1,10 +1,29 @@
 {
-  "$schema": "https://json.schemastore.org/tsconfig",
-  "display": "Node 18",
-  "extends": "./base.json",
+  "$schema": "https://www.schemastore.org/tsconfig",
+  "display": "Node 24",
   "compilerOptions": {
-    "lib": ["ES2020"],
-    "module": "commonjs",
-    "target": "ES2020"
+    "target": "ES2024",
+    "lib": [
+      "ES2024",
+      "ESNext.Array",
+      "ESNext.Collection",
+      "ESNext.Iterator",
+      "ESNext.Promise"
+    ],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "moduleDetection": "force",
+    "types": [
+      "node"
+    ],
+    "resolveJsonModule": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "rewriteRelativeImportExtensions": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true
   }
 }

package/package.json

@@ -1,23 +1,19 @@
 {
   "name": "@mkappelhof/ts-config",
-  "version": "1.0.6",
+  "version": "2.1.0",
   "main": "base.json",
   "license": "MIT",
   "repository": "git@github.com:mkappelhof/frontend-tools.git",
   "author": "Maurice Kappelhof <maurice@mauricekappelhof.nl>",
   "scripts": {
-    "build": "rollup -c",
     "test": "echo 'No test step'"
   },
   "peerDependencies": {
-    "typescript": "5.1.6"
-  },
-  "devDependencies": {
-    "@rollup/plugin-json": "6.0.0"
+    "typescript": "^6.0.0 || ^7.0.0"
   },
   "tags": [
     "typescript",
     "tsconfig",
     "config"
   ]
-}
+}

package/react.json

@@ -1,11 +1,26 @@
 {
-  "$schema": "https://json.schemastore.org/tsconfig",
-  "display": "React Library",
-  "extends": "./base.json",
+  "$schema": "https://www.schemastore.org/tsconfig",
+  "display": "React",
   "compilerOptions": {
-    "jsx": "react-jsx",
-    "lib": ["dom", "ES2015"],
+    "target": "ES2023",
+    "lib": [
+      "DOM",
+      "DOM.Iterable",
+      "ES2023"
+    ],
     "module": "ESNext",
-    "target": "es6"
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "noEmit": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true
   }
-}
+}

package/remix.json

@@ -3,10 +3,14 @@
   "display": "Remix",
   "extends": "./base.json",
   "compilerOptions": {
-    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "lib": [
+      "DOM",
+      "DOM.Iterable",
+      "ESNext"
+    ],
     "jsx": "react-jsx",
     "moduleResolution": "node",
     "target": "ESNext",
     "baseUrl": "."
   }
-}
+}

package/rollup.config.js

@@ -1,22 +0,0 @@
-const copy = require("rollup-plugin-copy");
-const json = require("@rollup/plugin-json");
-
-module.exports = {
-  input: "./base.json",
-  output: {
-    file: "./dist/base.json",
-    format: "cjs",
-  },
-  plugins: [
-    json(),
-    copy({
-      targets: [
-        { src: "./next.json", dest: "./dist/" },
-        { src: "./node.json", dest: "./dist/" },
-        { src: "./react.json", dest: "./dist/" },
-        { src: "./CHANGELOG.md", dest: "./dist/" },
-        { src: "./package.json", dest: "./dist/" },
-      ],
-    }),
-  ],
-};