@codefast/typescript-config 0.8.0 → 0.9.1

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,53 @@
1
1
  # @codefast/typescript-config
2
2
 
3
+ ## 0.9.1
4
+
5
+ ### Patch Changes
6
+
7
+ - [#892](https://github.com/codefastlabs/codefast/pull/892) [`4c97c5b`](https://github.com/codefastlabs/codefast/commit/4c97c5b8c2314f25ee9df7eac5a4b5dd723d6d90) Thanks [@thevuong](https://github.com/thevuong)! - Lower the monorepo's Node floor from 24 to 22.12, so the packages install and run on the active Node 22 LTS line.
8
+
9
+ `engines.node` becomes `>=22.12.0` across every package — the floor the shared toolchain (oxlint, Vite, Vitest, TanStack
10
+ Start) already requires. Development stays on the latest Node (`.node-version`) for speed, and a CI matrix exercises the
11
+ floor and the active LTS directly, so the floor is a contract CI proves rather than one everyone has to run.
12
+ `@types/node` is pinned to the floor's major (`^22`), with a workspace override holding the whole tree there so a dev
13
+ tool's `@types/node: "*"` peer can no longer pull a newer major and mask an API the floor lacks. The floor stays
14
+ mechanical, not advisory: `@codefast/di` keeps its own `Map` upsert helpers rather than the ES2025
15
+ `Map.prototype.getOrInsert` (which would raise the floor to 26) and its `lib` stays `ES2024`. `@codefast/cli`'s mirror
16
+ step now calls the `node:path` functions directly instead of aliasing them, which the floor's types correctly flag as
17
+ unbound methods.
18
+
19
+ The shared `@codefast/typescript-config` presets pin `lib` and `target` to `ES2024` (was `ESNext`) so the compiler's
20
+ ECMAScript surface matches the Node floor: an ES2025 builtin such as `Map.prototype.getOrInsert` now fails to type-check
21
+ rather than compiling and crashing on Node 22.12. `@codefast/di` and `@codefast/di-testing` already pinned `lib` and are
22
+ unchanged.
23
+
24
+ Internal subpath imports move from a `#/` prefix to a bare `#` (`#core/token`, not `#/core/token`), and the
25
+ `package.json#imports` keys become `#*`/`#tests/*`/`#examples/*` to match. Node's native ESM resolver rejects a
26
+ `#/`-prefixed specifier with `ERR_INVALID_MODULE_SPECIFIER` on the whole Node 22 line (and on Node 24 before 24.14), and
27
+ each package ships those specifiers verbatim inside its published `dist/*.js` for a consumer's Node to resolve — so this
28
+ rename is what actually lets the packages import on the new floor. Purely internal: a consumer's own import paths are
29
+ unchanged.
30
+
31
+ ## 0.9.0
32
+
33
+ ### Minor Changes
34
+
35
+ - [#809](https://github.com/codefastlabs/codefast/pull/809) [`7485645`](https://github.com/codefastlabs/codefast/commit/74856453cc18f38aed156af0ccb2970c0199477f) Thanks [@thevuong](https://github.com/thevuong)! - `exactOptionalPropertyTypes` now defaults to `true` in `base.json`, so every preset (`base`, `library`, `react`) turns
36
+ it on and each package inherits one source of truth instead of repeating the flag. Packages not yet ready for it opt out
37
+ explicitly with `"exactOptionalPropertyTypes": false` (`@codefast/cli`, `@codefast/tailwind-variants`, and the private
38
+ benchmark packages). A consumer extending these presets will now type-check under `exactOptionalPropertyTypes`; set it
39
+ back to `false` locally if that surfaces errors you are not ready to fix.
40
+
41
+ ### Patch Changes
42
+
43
+ - [#791](https://github.com/codefastlabs/codefast/pull/791) [`37a212b`](https://github.com/codefastlabs/codefast/commit/37a212b4d805588413159e11e872b98db82326bf) Thanks [@thevuong](https://github.com/thevuong)! - Point the README's license badge and "License" section at the package's own `LICENSE` file instead of the monorepo root.
44
+
45
+ - [#793](https://github.com/codefastlabs/codefast/pull/793) [`83cceeb`](https://github.com/codefastlabs/codefast/commit/83cceeb2168e063441125643a83e9555fb2d2048) Thanks [@thevuong](https://github.com/thevuong)! - Make "MIT" in the README's License section the link to the package's `LICENSE` file.
46
+
47
+ - [#796](https://github.com/codefastlabs/codefast/pull/796) [`ba04d27`](https://github.com/codefastlabs/codefast/commit/ba04d2703c59a1677f52e6a9fffd0ec202328218) Thanks [@thevuong](https://github.com/thevuong)! - Rewrite the README around one structure — what the package is, installation and requirements, a complete quick start,
48
+ the concepts in learning order, then the documents and the license — with every API claim checked against the current
49
+ code and no figures that go stale.
50
+
3
51
  ## 0.8.0
4
52
 
5
53
  ### Minor Changes
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2024 CodeFast Labs
3
+ Copyright (c) 2024 Codefast Labs
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -1,10 +1,27 @@
1
1
  # @codefast/typescript-config
2
2
 
3
- Shared TypeScript configuration presets — one strict, bundler-first base, focused variants for libraries, React, and
4
- Next.js, and a build overlay that turns on `.d.ts` emit.
3
+ Shared TypeScript configuration presets for projects that want one strict, bundler-first baseline and small, focused
4
+ variants for libraries, React, and Next.js.
5
5
 
6
6
  [![npm version](https://img.shields.io/npm/v/@codefast/typescript-config)](https://www.npmjs.com/package/@codefast/typescript-config)
7
- [![license](https://img.shields.io/npm/l/@codefast/typescript-config)](https://github.com/codefastlabs/codefast/blob/main/LICENSE)
7
+ [![license](https://img.shields.io/npm/l/@codefast/typescript-config)](./LICENSE)
8
+
9
+ ## Overview
10
+
11
+ `@codefast/typescript-config` gives you one strict, bundler-first TypeScript baseline and a few focused variants — for
12
+ libraries, React, and Next.js. Extend the preset that fits your project, then override anything you need locally.
13
+
14
+ The presets are plain JSON `tsconfig` files. There's no runtime code, and nothing to import.
15
+
16
+ - **Strict by default.** `strict`, `noUncheckedIndexedAccess`, `noImplicitOverride`, and `verbatimModuleSyntax` come
17
+ from the base that every preset extends.
18
+ - **Bundler-first.** An ESNext `module` with `moduleResolution: "bundler"`, so `exports` and `imports` maps resolve the
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.
23
+ - **Type-check only.** The presets set `noEmit`; a separate build overlay turns on emit and `.d.ts` generation.
24
+ - **Plain JSON.** No runtime code, nothing to import.
8
25
 
9
26
  ## Installation
10
27
 
@@ -12,15 +29,14 @@ Next.js, and a build overlay that turns on `.d.ts` emit.
12
29
  pnpm add -D @codefast/typescript-config
13
30
  ```
14
31
 
15
- TypeScript >= 5.0 is a peer dependency (`moduleResolution: "bundler"` requires it). The package ships plain JSON — it
16
- adds no runtime code.
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.
17
35
 
18
- ## Usage
36
+ ## Quick start
19
37
 
20
- Extend the preset that matches your project in `tsconfig.json`. Keep the `.json` extension — the package export map only
21
- exposes the full file names.
22
-
23
- A generic TypeScript project:
38
+ Extend the preset that matches your project in `tsconfig.json`. Keep the `.json` extension — the package exports the
39
+ full file names only.
24
40
 
25
41
  ```json
26
42
  {
@@ -29,6 +45,29 @@ A generic TypeScript project:
29
45
  }
30
46
  ```
31
47
 
48
+ Options you set locally always win, so overriding a preset value takes one line:
49
+
50
+ ```json
51
+ {
52
+ "extends": "@codefast/typescript-config/library.json",
53
+ "compilerOptions": {
54
+ "lib": ["DOM", "DOM.Iterable", "ES2024"]
55
+ }
56
+ }
57
+ ```
58
+
59
+ ## Presets
60
+
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"]`. |
68
+
69
+ ### Choosing a preset
70
+
32
71
  A publishable package with no browser coupling:
33
72
 
34
73
  ```json
@@ -56,40 +95,55 @@ A Next.js app:
56
95
  }
57
96
  ```
58
97
 
59
- Options you set locally always win, so overriding a preset value is a one-line change:
98
+ ### Building with `tsc`
99
+
100
+ `library-build.json` is an overlay, not a standalone preset. It carries only the emit options, so layer it over your
101
+ development config in a separate `tsconfig.build.json`. List both in `extends` to keep the strictness from
102
+ `library.json` and add `.d.ts` emit on top:
60
103
 
61
104
  ```json
62
105
  {
63
- "extends": "@codefast/typescript-config/library.json",
106
+ "extends": ["./tsconfig.json", "@codefast/typescript-config/library-build.json"],
64
107
  "compilerOptions": {
65
- "lib": ["DOM", "DOM.Iterable", "ESNext"]
66
- }
108
+ "rootDir": "./src",
109
+ "outDir": "./dist"
110
+ },
111
+ "include": ["src/**/*.ts"],
112
+ "exclude": ["src/**/*.test.ts"]
67
113
  }
68
114
  ```
69
115
 
70
- ## Presets
71
-
72
- | Preset | Extends | Purpose |
73
- | -------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
74
- | `base.json` | — | Strict, bundler-first baseline: ESNext target/module, DOM + ESNext libs, type-check only. |
75
- | `library.json` | `base.json` | Headless packages: drops the DOM libs so reliance on browser globals is a type error. |
76
- | `react.json` | `base.json` | React 17+ automatic JSX transform (`jsx: "react-jsx"`) — no `React` import needed. |
77
- | `next.json` | `base.json` | Next.js apps: `jsx: "preserve"`, incremental builds, and the `next` TypeScript plugin. |
78
- | `library-build.json` | (overlay) | Build-emit overrides layered over `library.json` in a build config: `noEmit: false`, `.d.ts` via `isolatedDeclarations`, plus declaration and source maps. |
116
+ Then `tsc -p tsconfig.build.json` emits `.js`, `.d.ts`, and their maps into `dist/`. `isolatedDeclarations` requires an
117
+ explicit type annotation on every export, which is what lets declarations be produced file by file.
79
118
 
80
119
  ## Notable compiler options
81
120
 
82
- All strictness comes from `base.json`, so every preset inherits it:
121
+ Every preset inherits its strictness from `base.json`:
83
122
 
84
123
  - `strict` — the full strict family (`strictNullChecks`, `noImplicitAny`, and friends).
85
124
  - `noUncheckedIndexedAccess` — indexed access is typed `T | undefined`, forcing explicit handling.
125
+ - `noImplicitOverride` — a method that overrides a base-class member must say `override`.
126
+ - `verbatimModuleSyntax` — type-only imports must be written `import type`, so a transpiler can drop them without type
127
+ information.
86
128
  - `isolatedModules` + `moduleDetection: "force"` — every file is a module and must transpile in isolation, as bundlers
87
129
  require.
88
130
  - `module: "ESNext"` + `moduleResolution: "bundler"` — modern ESM with bundler-style `exports`/`imports` resolution.
89
- - `noEmit` — presets type-check only; emitting is your bundler's job (override in a build config if `tsc` emits for
90
- you).
131
+ - `noEmit` — presets type-check only; emitting is your bundler's job, or `library-build.json`'s when `tsc` builds for
132
+ you.
91
133
  - `forceConsistentCasingInFileNames` — catches import-path casing mismatches before they break case-sensitive CI.
134
+ - `skipLibCheck`, `esModuleInterop`, `resolveJsonModule` — pragmatic defaults for consuming third-party packages and
135
+ JSON.
136
+
137
+ ## Documentation
138
+
139
+ - [codefastlabs.com/docs/typescript-config](https://codefastlabs.com/docs/typescript-config) — this document, rendered.
140
+ - [`CHANGELOG.md`](./CHANGELOG.md) — release notes for every published version.
141
+
142
+ ## Contributing
143
+
144
+ The package is developed in the [codefast monorepo](https://github.com/codefastlabs/codefast); the repo-wide
145
+ [contributing guide](../../CONTRIBUTING.md) covers setup, the test taxonomy, and the release flow.
92
146
 
93
147
  ## License
94
148
 
95
- MIT — see [LICENSE](https://github.com/codefastlabs/codefast/blob/main/LICENSE).
149
+ Released under the [MIT License](./LICENSE).
package/base.json CHANGED
@@ -2,9 +2,10 @@
2
2
  "$schema": "https://json.schemastore.org/tsconfig",
3
3
  "compilerOptions": {
4
4
  "esModuleInterop": true,
5
+ "exactOptionalPropertyTypes": true,
5
6
  "forceConsistentCasingInFileNames": true,
6
7
  "isolatedModules": true,
7
- "lib": ["DOM", "DOM.Iterable", "ESNext"],
8
+ "lib": ["DOM", "DOM.Iterable", "ES2024"],
8
9
  "module": "ESNext",
9
10
  "moduleDetection": "force",
10
11
  "moduleResolution": "bundler",
@@ -14,7 +15,7 @@
14
15
  "resolveJsonModule": true,
15
16
  "skipLibCheck": true,
16
17
  "strict": true,
17
- "target": "ESNext",
18
+ "target": "ES2024",
18
19
  "verbatimModuleSyntax": true
19
20
  },
20
21
  "display": "Base configuration for monorepo packages"
package/library.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/tsconfig",
3
3
  "compilerOptions": {
4
- "lib": ["ESNext"]
4
+ "lib": ["ES2024"]
5
5
  },
6
6
  "display": "Library development configuration",
7
7
  "extends": "./base.json"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@codefast/typescript-config",
3
- "version": "0.8.0",
3
+ "version": "0.9.1",
4
4
  "description": "Shared TypeScript configuration for the monorepo",
5
5
  "keywords": [
6
6
  "browser",
@@ -18,7 +18,7 @@
18
18
  "url": "https://github.com/codefastlabs/codefast/issues"
19
19
  },
20
20
  "license": "MIT",
21
- "author": "Vuong Phan <mr.thevuong@gmail.com>",
21
+ "author": "Vuong Phan <mr.thevuong@gmail.com> (https://github.com/thevuong)",
22
22
  "repository": {
23
23
  "type": "git",
24
24
  "url": "git+https://github.com/codefastlabs/codefast.git",
@@ -44,6 +44,6 @@
44
44
  "typescript": ">=5.0.0"
45
45
  },
46
46
  "engines": {
47
- "node": ">=24.0.0"
47
+ "node": ">=22.12.0"
48
48
  }
49
49
  }