@codefast/typescript-config 0.9.1 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,39 @@
1
1
  # @codefast/typescript-config
2
2
 
3
+ ## 0.11.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#1068](https://github.com/codefastlabs/codefast/pull/1068) Add the `node22.json` and `node22-dom.json` overlays, which narrow `lib` and `target` to what Node 22 ships for a
8
+ package whose floor is on Node 22, and lower the package's own Node.js floor to 22.12.
9
+
10
+ ## 0.10.0
11
+
12
+ ### Minor Changes
13
+
14
+ - [#976](https://github.com/codefastlabs/codefast/pull/976) `engines.node` is now `>=24.0.0`, up from `>=22.12.0`, and Node 22 is no longer supported. Node 24.0.0 is the first
15
+ release with explicit resource management built in (`using`, `await using`, `DisposableStack`, `AsyncDisposableStack`,
16
+ `SuppressedError`) and all of ES2025, so the packages use both as the platform ships them instead of shimming them for
17
+ an older line, and the CI matrix runs the unit suite on 24.0.0 itself. Move to Node 24, or stay on the current minor
18
+ while a deployment still runs Node 22.
19
+
20
+ - [#976](https://github.com/codefastlabs/codefast/pull/976) The presets' `lib` and `target` move from `ES2024` to `ES2025`, the newest edition that Node 24 and the supported
21
+ browsers both ship. `base.json`, and so `react.json` and `next.json`, lists `DOM`, `DOM.Iterable` and `ES2025`;
22
+ `library.json` lists `ES2025`. A program on a preset can use ES2025 builtins with no `lib` entry of its own, and a
23
+ builtin newer than that, such as `Map.prototype.getOrInsert`, is still a type error.
24
+
25
+ - [#965](https://github.com/codefastlabs/codefast/pull/965) The `typescript` peer range is now `>=7.0.0`, up from `>=5.0.0`: TypeScript 7 is the one compiler the presets are
26
+ checked against, so it is the floor they support. A project pinned to TypeScript 6 or older now fails npm's peer
27
+ resolution (`ERESOLVE`) and gets a pnpm peer warning. Move it to TypeScript 7, or stay on 0.9.x while its tooling still
28
+ needs TypeScript 6. A Next.js app on `next.json` needs Next.js 16.3 or later, the first release that type-checks with
29
+ TypeScript 7.
30
+
31
+ - [#977](https://github.com/codefastlabs/codefast/pull/977) `library-build.json` sets `types: []` instead of `["node"]`, so a build loads only the ambient types its own config
32
+ names. A package that runs on Node adds `types: ["node"]` to its `tsconfig.build.json`, which also brings explicit
33
+ resource management. A browser or universal package leaves it empty, so a Node global in its source fails the build. No
34
+ preset lists `ESNext.Disposable`: a Node program gets explicit resource management from `@types/node` 24 or later, and a
35
+ browser program adds it once the browsers it targets ship it, which Safari has not.
36
+
3
37
  ## 0.9.1
4
38
 
5
39
  ### Patch Changes
package/README.md CHANGED
@@ -17,9 +17,13 @@ The presets are plain JSON `tsconfig` files. There's no runtime code, and nothin
17
17
  from the base that every preset extends.
18
18
  - **Bundler-first.** An ESNext `module` with `moduleResolution: "bundler"`, so `exports` and `imports` maps resolve the
19
19
  way Vite, esbuild, and friends resolve them.
20
- - **`lib` and `target` are `ES2024`, matching the Node floor** (`engines.node >= 22.12`). ES2024 is the newest edition
21
- Node 22.12 fully supports, so an ES2025 builtin such as `Map.prototype.getOrInsert` is a type error here rather than a
22
- runtime crash on the floor. Bump both together only when the floor moves.
20
+ - **`lib` and `target` match the runtime floors**: both are `ES2025`, the newest edition that Node 24 and the browser
21
+ floor both ship ([support policy](../../SUPPORT.md)). A builtin newer than that, such as `Map.prototype.getOrInsert`,
22
+ is a type error here rather than a runtime crash on the floor. A package whose Node floor is 22 layers a floor overlay
23
+ on top, which narrows both to what Node 22 ships.
24
+ - **Ambient types follow the runtime.** No preset loads `@types/node` or lists `ESNext.Disposable`. A program that runs
25
+ on Node adds `types: ["node"]`, which brings the Node globals and explicit resource management with it. A browser
26
+ program leaves both out: Safari has not shipped explicit resource management yet.
23
27
  - **Type-check only.** The presets set `noEmit`; a separate build overlay turns on emit and `.d.ts` generation.
24
28
  - **Plain JSON.** No runtime code, nothing to import.
25
29
 
@@ -29,9 +33,9 @@ The presets are plain JSON `tsconfig` files. There's no runtime code, and nothin
29
33
  pnpm add -D @codefast/typescript-config
30
34
  ```
31
35
 
32
- `@codefast/typescript-config` requires Node.js 22.12 or later, and `typescript` 5 or later as a peer dependency —
33
- `moduleResolution: "bundler"` is a TypeScript 5 option. The package is published on 0.x and versioned on its own track:
34
- breaking changes ship as minor versions, so pin the minor version when you need stability.
36
+ `@codefast/typescript-config` requires Node.js 22.12 or later, and `typescript` 7 or later as a peer dependency —
37
+ TypeScript 7 is the one compiler the presets are checked against. The package is published on 0.x and versioned on its
38
+ own track: breaking changes ship as minor versions, so pin the minor version when you need stability.
35
39
 
36
40
  ## Quick start
37
41
 
@@ -45,30 +49,32 @@ full file names only.
45
49
  }
46
50
  ```
47
51
 
48
- Options you set locally always win, so overriding a preset value takes one line:
52
+ Options you set locally always win, so adjusting a preset takes one line — here, a package that runs on Node:
49
53
 
50
54
  ```json
51
55
  {
52
56
  "extends": "@codefast/typescript-config/library.json",
53
57
  "compilerOptions": {
54
- "lib": ["DOM", "DOM.Iterable", "ES2024"]
58
+ "types": ["node"]
55
59
  }
56
60
  }
57
61
  ```
58
62
 
59
63
  ## Presets
60
64
 
61
- | Preset | Extends | Purpose |
62
- | -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
63
- | `base.json` | — | Strict, bundler-first baseline: ES2024 target, ESNext module, DOM + ES2024 libs, type-check only. |
64
- | `library.json` | `base.json` | Headless packages: `lib` is `ES2024` only, so relying on a browser global is a type error. |
65
- | `react.json` | `base.json` | React with the automatic JSX runtime (`jsx: "react-jsx"`) — components need no `React` import. |
66
- | `next.json` | `base.json` | Next.js apps: `jsx: "preserve"`, `incremental` builds, and the `next` TypeScript plugin. |
67
- | `library-build.json` | (overlay) | Build-emit overrides for a build config: `noEmit: false`, `declaration` + `isolatedDeclarations`, declaration and source maps, `types: ["node"]`. |
65
+ | Preset | Extends | Purpose |
66
+ | -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
67
+ | `base.json` | — | Strict, bundler-first baseline: ES2025 target, ESNext module, DOM + ES2025 libs, type-check only. |
68
+ | `library.json` | `base.json` | Headless packages: `lib` is `ES2025` only, so relying on a browser global is a type error. A package that runs on Node adds `types: ["node"]`. |
69
+ | `react.json` | `base.json` | React with the automatic JSX runtime (`jsx: "react-jsx"`) — components need no `React` import. |
70
+ | `next.json` | `base.json` | Next.js apps: `jsx: "preserve"`, `incremental` builds, and the `next` TypeScript plugin. |
71
+ | `node22.json` | (overlay) | Node 22 floor for a headless package: `lib` is `ES2024` plus the Set methods and iterator helpers Node 22 ships, and `target` is `ES2024`. |
72
+ | `node22-dom.json` | (overlay) | Node 22 floor for a package that also renders in a browser: the same, with `DOM` and `DOM.Iterable`. |
73
+ | `library-build.json` | (overlay) | Build-emit overrides for a build config: `noEmit: false`, `declaration` + `isolatedDeclarations`, declaration and source maps, and `types: []`, so test-only ambient types stay out of the build. |
68
74
 
69
75
  ### Choosing a preset
70
76
 
71
- A publishable package with no browser coupling:
77
+ A publishable package with no browser coupling, which runs wherever JavaScript runs:
72
78
 
73
79
  ```json
74
80
  {
@@ -77,6 +83,18 @@ A publishable package with no browser coupling:
77
83
  }
78
84
  ```
79
85
 
86
+ A package or CLI that runs on Node:
87
+
88
+ ```json
89
+ {
90
+ "extends": "@codefast/typescript-config/library.json",
91
+ "compilerOptions": {
92
+ "types": ["node"]
93
+ },
94
+ "include": ["src"]
95
+ }
96
+ ```
97
+
80
98
  A React app or component library:
81
99
 
82
100
  ```json
@@ -95,6 +113,26 @@ A Next.js app:
95
113
  }
96
114
  ```
97
115
 
116
+ Next.js 16.3 and later type-check with TypeScript 7 through its `tsc` CLI (`experimental.useTypeScriptCli`, on by
117
+ default). Earlier Next.js releases need TypeScript 6's compiler API, so an app on one of them stays on 0.9.x of this
118
+ package.
119
+
120
+ ### Targeting a Node 22 floor
121
+
122
+ The presets assume Node 24. A package whose `engines.node` floor is on Node 22 lists a floor overlay last in `extends`,
123
+ so `lib` and `target` drop to what Node 22 ships and `RegExp.escape`, `Promise.try`, `Float16Array` or a regular
124
+ expression modifier become type errors rather than crashes on the floor:
125
+
126
+ ```json
127
+ {
128
+ "extends": ["@codefast/typescript-config/react.json", "@codefast/typescript-config/node22-dom.json"],
129
+ "include": ["src"]
130
+ }
131
+ ```
132
+
133
+ `node22.json` replaces `lib` with no DOM, so a headless package pairs it with `library.json`; a package that renders in
134
+ a browser takes `node22-dom.json` instead. A local `lib` still wins over both.
135
+
98
136
  ### Building with `tsc`
99
137
 
100
138
  `library-build.json` is an overlay, not a standalone preset. It carries only the emit options, so layer it over your
@@ -116,6 +154,10 @@ development config in a separate `tsconfig.build.json`. List both in `extends` t
116
154
  Then `tsc -p tsconfig.build.json` emits `.js`, `.d.ts`, and their maps into `dist/`. `isolatedDeclarations` requires an
117
155
  explicit type annotation on every export, which is what lets declarations be produced file by file.
118
156
 
157
+ The overlay sets `types: []`, so the test types your development config loads (`vitest/globals`, for example) stay out
158
+ of the build. A package that runs on Node sets `types: ["node"]` again in its `tsconfig.build.json`. A browser or
159
+ universal package leaves it empty, so a Node global in its source fails the build.
160
+
119
161
  ## Notable compiler options
120
162
 
121
163
  Every preset inherits its strictness from `base.json`:
package/base.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "exactOptionalPropertyTypes": true,
6
6
  "forceConsistentCasingInFileNames": true,
7
7
  "isolatedModules": true,
8
- "lib": ["DOM", "DOM.Iterable", "ES2024"],
8
+ "lib": ["DOM", "DOM.Iterable", "ES2025"],
9
9
  "module": "ESNext",
10
10
  "moduleDetection": "force",
11
11
  "moduleResolution": "bundler",
@@ -15,7 +15,7 @@
15
15
  "resolveJsonModule": true,
16
16
  "skipLibCheck": true,
17
17
  "strict": true,
18
- "target": "ES2024",
18
+ "target": "ES2025",
19
19
  "verbatimModuleSyntax": true
20
20
  },
21
21
  "display": "Base configuration for monorepo packages"
@@ -7,6 +7,6 @@
7
7
  "isolatedDeclarations": true,
8
8
  "declarationMap": true,
9
9
  "sourceMap": true,
10
- "types": ["node"]
10
+ "types": []
11
11
  }
12
12
  }
package/library.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/tsconfig",
3
3
  "compilerOptions": {
4
- "lib": ["ES2024"]
4
+ "lib": ["ES2025"]
5
5
  },
6
6
  "display": "Library development configuration",
7
7
  "extends": "./base.json"
@@ -0,0 +1,8 @@
1
+ {
2
+ "$schema": "https://json.schemastore.org/tsconfig",
3
+ "compilerOptions": {
4
+ "lib": ["DOM", "DOM.Iterable", "ES2024", "ES2025.Collection", "ES2025.Iterator"],
5
+ "target": "ES2024"
6
+ },
7
+ "display": "Node 22 floor overlay for packages that also render in a browser"
8
+ }
package/node22.json ADDED
@@ -0,0 +1,8 @@
1
+ {
2
+ "$schema": "https://json.schemastore.org/tsconfig",
3
+ "compilerOptions": {
4
+ "lib": ["ES2024", "ES2025.Collection", "ES2025.Iterator"],
5
+ "target": "ES2024"
6
+ },
7
+ "display": "Node 22 floor overlay for headless packages"
8
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@codefast/typescript-config",
3
- "version": "0.9.1",
3
+ "version": "0.11.0",
4
4
  "description": "Shared TypeScript configuration for the monorepo",
5
5
  "keywords": [
6
6
  "browser",
@@ -35,13 +35,15 @@
35
35
  "./library.json": "./library.json",
36
36
  "./library-build.json": "./library-build.json",
37
37
  "./next.json": "./next.json",
38
+ "./node22.json": "./node22.json",
39
+ "./node22-dom.json": "./node22-dom.json",
38
40
  "./react.json": "./react.json"
39
41
  },
40
42
  "publishConfig": {
41
43
  "access": "public"
42
44
  },
43
45
  "peerDependencies": {
44
- "typescript": ">=5.0.0"
46
+ "typescript": ">=7.0.0"
45
47
  },
46
48
  "engines": {
47
49
  "node": ">=22.12.0"