@codefast/typescript-config 0.3.13-canary.4 → 0.3.14-canary.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 +18 -0
- package/README.md +214 -175
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
# @codefast/typescript-config
|
|
2
2
|
|
|
3
|
+
## 0.3.14-canary.0
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- [`8109f4e`](https://github.com/codefastlabs/codefast/commit/8109f4e1f8186b91c296d25d640594b43493cdef) Thanks [@thevuong](https://github.com/thevuong)! - docs: update README.md files across packages for consistency and clarity
|
|
8
|
+
|
|
9
|
+
- [`8c918c3`](https://github.com/codefastlabs/codefast/commit/8c918c36a19e5f25e8b267c6d20af9b882306236) Thanks [@thevuong](https://github.com/thevuong)! - docs(typescript-config): enhance README.md for clarity and structure
|
|
10
|
+
|
|
11
|
+
## 0.3.13
|
|
12
|
+
|
|
13
|
+
### Patch Changes
|
|
14
|
+
|
|
15
|
+
- [`a042ee5`](https://github.com/codefastlabs/codefast/commit/a042ee5a6a10973492665b90d750a8b86817bf7d) Thanks [@thevuong](https://github.com/thevuong)! - feat: standardize TypeScript build configurations across packages
|
|
16
|
+
|
|
17
|
+
- [`2340231`](https://github.com/codefastlabs/codefast/commit/23402311084871d238ec50aa23061afd4b14e61e) Thanks [@thevuong](https://github.com/thevuong)! - refactor(imports): standardize import paths across applications and benchmarks
|
|
18
|
+
|
|
19
|
+
- [`35329d5`](https://github.com/codefastlabs/codefast/commit/35329d5f17682542e3ef0907d4936fa513346a72) Thanks [@thevuong](https://github.com/thevuong)! - feat(tsconfig): enforce module detection in TypeScript configuration
|
|
20
|
+
|
|
3
21
|
## 0.3.13-canary.4
|
|
4
22
|
|
|
5
23
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @codefast/typescript-config
|
|
2
2
|
|
|
3
|
-
Shared TypeScript
|
|
3
|
+
Shared TypeScript compiler configurations for the `codefast` ecosystem — one strict base preset plus focused specialisations for libraries, React, and Next.js.
|
|
4
4
|
|
|
5
5
|
[](https://github.com/codefastlabs/codefast/actions/workflows/release.yml)
|
|
6
6
|
[](https://www.npmjs.com/package/@codefast/typescript-config)
|
|
@@ -10,15 +10,16 @@ Shared TypeScript configuration presets providing standardized compiler settings
|
|
|
10
10
|
## Table of Contents
|
|
11
11
|
|
|
12
12
|
- [Overview](#overview)
|
|
13
|
+
- [Requirements](#requirements)
|
|
13
14
|
- [Installation](#installation)
|
|
14
15
|
- [Quick Start](#quick-start)
|
|
15
|
-
- [
|
|
16
|
-
- [
|
|
17
|
-
- [
|
|
18
|
-
- [
|
|
19
|
-
- [
|
|
20
|
-
- [
|
|
21
|
-
- [
|
|
16
|
+
- [Presets](#presets)
|
|
17
|
+
- [base.json](#basejson)
|
|
18
|
+
- [library.json](#libraryjson)
|
|
19
|
+
- [react.json](#reactjson)
|
|
20
|
+
- [next.json](#nextjson)
|
|
21
|
+
- [Usage Recipes](#usage-recipes)
|
|
22
|
+
- [Strictness at a Glance](#strictness-at-a-glance)
|
|
22
23
|
- [Compatibility](#compatibility)
|
|
23
24
|
- [Troubleshooting](#troubleshooting)
|
|
24
25
|
- [Contributing](#contributing)
|
|
@@ -27,290 +28,328 @@ Shared TypeScript configuration presets providing standardized compiler settings
|
|
|
27
28
|
|
|
28
29
|
## Overview
|
|
29
30
|
|
|
30
|
-
|
|
31
|
+
This package ships four JSON files that you reference from your project's `tsconfig.json` via `extends`. Every preset inherits from `base.json`, so each specialisation only layers on the options it actually needs.
|
|
31
32
|
|
|
32
|
-
|
|
33
|
+
Design goals:
|
|
33
34
|
|
|
34
|
-
- **Strict
|
|
35
|
-
- **Modern
|
|
36
|
-
- **Bundler
|
|
37
|
-
- **
|
|
38
|
-
- **
|
|
39
|
-
|
|
35
|
+
- **Strict by default** — full `strict` mode plus `noUncheckedIndexedAccess`.
|
|
36
|
+
- **Modern targets** — `ESNext` target and module, tuned for bundler-driven builds.
|
|
37
|
+
- **Bundler-first** — `moduleResolution: "bundler"` works cleanly with Vite, Turbopack, esbuild, webpack 5, Next.js, Rollup / Rolldown, and `tsdown`.
|
|
38
|
+
- **Tree-shakeable ESM** — `isolatedModules` + `moduleDetection: "force"` guarantee every file is a module.
|
|
39
|
+
- **No emit** — the preset assumes a separate bundler or transpiler is responsible for output (`noEmit: true`).
|
|
40
|
+
|
|
41
|
+
## Requirements
|
|
42
|
+
|
|
43
|
+
- TypeScript **>= 5.0** — `moduleResolution: "bundler"` requires TS 5.0+; `verbatimModuleSyntax` awareness works best on 5.2+
|
|
44
|
+
|
|
45
|
+
No runtime dependency is added to your application — the package is pure JSON.
|
|
40
46
|
|
|
41
47
|
## Installation
|
|
42
48
|
|
|
43
49
|
```bash
|
|
44
50
|
pnpm add -D @codefast/typescript-config
|
|
51
|
+
# or
|
|
52
|
+
npm install --save-dev @codefast/typescript-config
|
|
53
|
+
# or
|
|
54
|
+
yarn add -D @codefast/typescript-config
|
|
45
55
|
```
|
|
46
56
|
|
|
47
|
-
|
|
57
|
+
## Quick Start
|
|
48
58
|
|
|
49
|
-
|
|
50
|
-
|
|
59
|
+
Pick the preset closest to your project type and `extends` it:
|
|
60
|
+
|
|
61
|
+
```json5
|
|
62
|
+
// tsconfig.json
|
|
63
|
+
{
|
|
64
|
+
extends: "@codefast/typescript-config/base.json",
|
|
65
|
+
include: ["src/**/*"],
|
|
66
|
+
exclude: ["node_modules", "dist"],
|
|
67
|
+
}
|
|
51
68
|
```
|
|
52
69
|
|
|
53
|
-
|
|
70
|
+
Override or extend any option locally. Overrides applied in the consumer's `tsconfig.json` always win.
|
|
54
71
|
|
|
55
|
-
|
|
56
|
-
- TypeScript >= 5.0.0
|
|
72
|
+
## Presets
|
|
57
73
|
|
|
58
|
-
|
|
74
|
+
| Preset | Inherits | `lib` | `jsx` | Extra | When to use |
|
|
75
|
+
| -------------- | ----------- | --------------------------- | ----------- | -------------------------------------------- | ----------------------------------------------- |
|
|
76
|
+
| `base.json` | — | `DOM, DOM.Iterable, ESNext` | — | — | Generic TypeScript projects (CLIs, scripts). |
|
|
77
|
+
| `library.json` | `base.json` | `ESNext` (DOM removed) | — | — | Publishable packages with no browser coupling. |
|
|
78
|
+
| `react.json` | `base.json` | (inherited) | `react-jsx` | — | React apps and component libraries (React 17+). |
|
|
79
|
+
| `next.json` | `base.json` | (inherited) | `preserve` | `incremental`, `plugins: [{ name: "next" }]` | Next.js apps (App Router or Pages Router). |
|
|
59
80
|
|
|
60
|
-
|
|
81
|
+
### base.json
|
|
82
|
+
|
|
83
|
+
Sets the strict, modern baseline used by every other preset.
|
|
61
84
|
|
|
62
85
|
```json
|
|
63
86
|
{
|
|
64
|
-
"
|
|
87
|
+
"compilerOptions": {
|
|
88
|
+
"allowJs": true,
|
|
89
|
+
"esModuleInterop": true,
|
|
90
|
+
"isolatedModules": true,
|
|
91
|
+
"lib": ["DOM", "DOM.Iterable", "ESNext"],
|
|
92
|
+
"module": "ESNext",
|
|
93
|
+
"moduleDetection": "force",
|
|
94
|
+
"moduleResolution": "bundler",
|
|
95
|
+
"noEmit": true,
|
|
96
|
+
"noUncheckedIndexedAccess": true,
|
|
97
|
+
"resolveJsonModule": true,
|
|
98
|
+
"skipLibCheck": true,
|
|
99
|
+
"strict": true,
|
|
100
|
+
"target": "ESNext"
|
|
101
|
+
}
|
|
65
102
|
}
|
|
66
103
|
```
|
|
67
104
|
|
|
68
|
-
|
|
105
|
+
| Option | Value | Why |
|
|
106
|
+
| ----------------------------- | --------------------------- | ----------------------------------------------------------------------------------------- |
|
|
107
|
+
| `strict` | `true` | Turns on the full strict family (`strictNullChecks`, `noImplicitAny`, etc.). |
|
|
108
|
+
| `noUncheckedIndexedAccess` | `true` | `arr[i]` and `obj[key]` are typed `T \| undefined` — forces explicit handling. |
|
|
109
|
+
| `target` | `ESNext` | Compile to the newest JavaScript; the bundler / runtime downlevels if needed. |
|
|
110
|
+
| `module` / `moduleResolution` | `ESNext` / `bundler` | Native ESM output with bundler-style `exports`/`imports` resolution. |
|
|
111
|
+
| `moduleDetection` | `force` | Treats every file as a module — no accidental global script files. |
|
|
112
|
+
| `isolatedModules` | `true` | Each file must be transpilable in isolation (required by esbuild, swc, Vite, Babel). |
|
|
113
|
+
| `lib` | `DOM, DOM.Iterable, ESNext` | Browser globals + the current ECMAScript surface. |
|
|
114
|
+
| `noEmit` | `true` | Type-checking only — emit is handled by tsdown / tsc-on-the-side / bundler. |
|
|
115
|
+
| `allowJs` | `true` | Permits mixed `.js`/`.ts` codebases. |
|
|
116
|
+
| `resolveJsonModule` | `true` | `import data from "./file.json"` works out of the box. |
|
|
117
|
+
| `esModuleInterop` | `true` | Interop with CommonJS default imports. |
|
|
118
|
+
| `skipLibCheck` | `true` | Skips type-checking of declaration files — faster, and sidesteps noisy third-party types. |
|
|
69
119
|
|
|
70
|
-
###
|
|
120
|
+
### library.json
|
|
71
121
|
|
|
72
|
-
|
|
122
|
+
Drops `DOM` / `DOM.Iterable` so accidental reliance on browser globals surfaces as a type error. Use for headless packages (utilities, server-side code, SDKs).
|
|
73
123
|
|
|
74
124
|
```json
|
|
75
125
|
{
|
|
76
|
-
"extends": "
|
|
126
|
+
"extends": "./base.json",
|
|
77
127
|
"compilerOptions": {
|
|
78
|
-
"
|
|
79
|
-
}
|
|
80
|
-
"include": ["src/**/*"],
|
|
81
|
-
"exclude": ["node_modules", "dist"]
|
|
128
|
+
"lib": ["ESNext"]
|
|
129
|
+
}
|
|
82
130
|
}
|
|
83
131
|
```
|
|
84
132
|
|
|
85
|
-
|
|
133
|
+
If a given library genuinely needs DOM types (e.g. the UI component library in this repo), re-add them locally — see [Troubleshooting](#conflicting-lib-settings).
|
|
134
|
+
|
|
135
|
+
### react.json
|
|
86
136
|
|
|
87
|
-
|
|
137
|
+
Enables the React 17+ automatic JSX transform so components don't need `import React from "react"`.
|
|
88
138
|
|
|
89
139
|
```json
|
|
90
140
|
{
|
|
91
|
-
"extends": "
|
|
141
|
+
"extends": "./base.json",
|
|
92
142
|
"compilerOptions": {
|
|
93
|
-
"
|
|
94
|
-
|
|
95
|
-
},
|
|
96
|
-
"include": ["src/**/*"],
|
|
97
|
-
"exclude": ["node_modules", "dist", "**/*.test.ts"]
|
|
143
|
+
"jsx": "react-jsx"
|
|
144
|
+
}
|
|
98
145
|
}
|
|
99
146
|
```
|
|
100
147
|
|
|
101
|
-
###
|
|
148
|
+
### next.json
|
|
102
149
|
|
|
103
|
-
|
|
150
|
+
Next.js owns the JSX transform itself, so `jsx` is set to `preserve` and incremental build caching is enabled. The `next` TypeScript plugin adds Route-type awareness and IDE features.
|
|
104
151
|
|
|
105
152
|
```json
|
|
106
153
|
{
|
|
107
|
-
"extends": "
|
|
154
|
+
"extends": "./base.json",
|
|
108
155
|
"compilerOptions": {
|
|
109
|
-
"
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
156
|
+
"incremental": true,
|
|
157
|
+
"jsx": "preserve",
|
|
158
|
+
"plugins": [{ "name": "next" }]
|
|
159
|
+
}
|
|
113
160
|
}
|
|
114
161
|
```
|
|
115
162
|
|
|
116
|
-
|
|
163
|
+
## Usage Recipes
|
|
117
164
|
|
|
118
|
-
|
|
165
|
+
### TypeScript library package (tsdown / tsc build)
|
|
119
166
|
|
|
120
|
-
```
|
|
167
|
+
```json5
|
|
121
168
|
{
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
169
|
+
extends: "@codefast/typescript-config/library.json",
|
|
170
|
+
compilerOptions: {
|
|
171
|
+
outDir: "./dist",
|
|
172
|
+
declaration: true,
|
|
173
|
+
declarationMap: true,
|
|
174
|
+
},
|
|
175
|
+
include: ["src/**/*"],
|
|
176
|
+
exclude: ["dist", "**/*.test.ts", "**/*.test.tsx"],
|
|
125
177
|
}
|
|
126
178
|
```
|
|
127
179
|
|
|
128
|
-
|
|
180
|
+
Since the preset leaves `noEmit: true`, many packages split responsibilities:
|
|
129
181
|
|
|
130
|
-
|
|
182
|
+
- `tsconfig.json` — for editors & `tsc --noEmit` type-checking.
|
|
183
|
+
- `tsconfig.build.json` — extends the same preset but sets `"noEmit": false` (or no override needed if your build tool emits directly).
|
|
131
184
|
|
|
132
|
-
|
|
133
|
-
| -------------- | ----------- | ------------------------------------------------ | ------------------------------ |
|
|
134
|
-
| `base.json` | -- | Strict base configuration with ESNext target | All TypeScript projects |
|
|
135
|
-
| `library.json` | `base.json` | ESNext-only libs (no DOM) | NPM packages, shared libraries |
|
|
136
|
-
| `react.json` | `base.json` | Adds `react-jsx` transform | React components and apps |
|
|
137
|
-
| `next.json` | `base.json` | Incremental builds, JSX preserve, Next.js plugin | Next.js applications |
|
|
185
|
+
### React component library
|
|
138
186
|
|
|
139
|
-
|
|
187
|
+
```json5
|
|
188
|
+
{
|
|
189
|
+
extends: "@codefast/typescript-config/react.json",
|
|
190
|
+
compilerOptions: {
|
|
191
|
+
lib: ["DOM", "DOM.Iterable", "ESNext"],
|
|
192
|
+
outDir: "./dist",
|
|
193
|
+
},
|
|
194
|
+
include: ["src/**/*"],
|
|
195
|
+
}
|
|
196
|
+
```
|
|
140
197
|
|
|
141
|
-
|
|
142
|
-
| ------------------- | --------------------------- | ---------------------------------------- |
|
|
143
|
-
| `strict` | `true` | Enables all strict type-checking options |
|
|
144
|
-
| `target` | `ESNext` | Latest JavaScript features |
|
|
145
|
-
| `module` | `ESNext` | ESM module system |
|
|
146
|
-
| `moduleResolution` | `bundler` | Optimized for modern bundlers |
|
|
147
|
-
| `lib` | `DOM, DOM.Iterable, ESNext` | Browser and ESNext APIs |
|
|
148
|
-
| `isolatedModules` | `true` | File-level transpilation |
|
|
149
|
-
| `noEmit` | `true` | Lets the bundler handle output |
|
|
150
|
-
| `allowJs` | `true` | JavaScript file support |
|
|
151
|
-
| `resolveJsonModule` | `true` | JSON import support |
|
|
152
|
-
| `esModuleInterop` | `true` | CommonJS/ESM interop |
|
|
153
|
-
| `skipLibCheck` | `true` | Skip type checking of declaration files |
|
|
198
|
+
### Next.js application
|
|
154
199
|
|
|
155
|
-
|
|
200
|
+
```json5
|
|
201
|
+
{
|
|
202
|
+
extends: "@codefast/typescript-config/next.json",
|
|
203
|
+
include: ["next-env.d.ts", ".next/types/**/*.ts", "**/*.ts", "**/*.tsx"],
|
|
204
|
+
exclude: ["node_modules"],
|
|
205
|
+
}
|
|
206
|
+
```
|
|
156
207
|
|
|
157
|
-
|
|
208
|
+
### Monorepo package with internal subpath imports
|
|
158
209
|
|
|
159
|
-
|
|
160
|
-
| ------ | -------- | ------------------------------------------------------------- |
|
|
161
|
-
| `lib` | `ESNext` | No DOM libs -- library code should not depend on browser APIs |
|
|
210
|
+
Pair the preset with `package.json#imports` for readable internal paths:
|
|
162
211
|
|
|
163
|
-
|
|
212
|
+
```json5
|
|
213
|
+
// package.json
|
|
214
|
+
{
|
|
215
|
+
type: "module",
|
|
216
|
+
imports: {
|
|
217
|
+
"#/*": ["./src/*", "./src/*.ts", "./src/*.tsx"],
|
|
218
|
+
},
|
|
219
|
+
}
|
|
220
|
+
```
|
|
164
221
|
|
|
165
|
-
|
|
222
|
+
`moduleResolution: "bundler"` resolves `#/*` specifiers natively — no `paths` mapping needed.
|
|
166
223
|
|
|
167
|
-
|
|
168
|
-
| ------ | ----------- | ----------------------------------------------- |
|
|
169
|
-
| `jsx` | `react-jsx` | Modern JSX transform (no `import React` needed) |
|
|
224
|
+
## Strictness at a Glance
|
|
170
225
|
|
|
171
|
-
|
|
226
|
+
Some consequences of the strict defaults are easy to miss. Expect the following to be errors out of the box:
|
|
172
227
|
|
|
173
|
-
|
|
228
|
+
| Pattern | Why it fails |
|
|
229
|
+
| ------------------------------------------------- | ---------------------------------------------------------------------------- |
|
|
230
|
+
| `const first = arr[0].name` | `noUncheckedIndexedAccess` — `arr[0]` is `T \| undefined`. |
|
|
231
|
+
| `function f(x) { return x + 1 }` | `strict` — `x` has an implicit `any`. |
|
|
232
|
+
| `let value; value = doSomething();` | Depending on `doSomething()`'s return, may be `undefined`. |
|
|
233
|
+
| `// @ts-ignore` without a reason | Not auto-forbidden, but `@ts-expect-error` is preferred when you want noise. |
|
|
234
|
+
| Forgetting `void` on a boolean-returning callback | `strictFunctionTypes` can flip arity / return-type compatibility. |
|
|
174
235
|
|
|
175
|
-
|
|
176
|
-
| ------------- | ---------------------- | ------------------------------------- |
|
|
177
|
-
| `incremental` | `true` | Faster subsequent builds |
|
|
178
|
-
| `jsx` | `preserve` | Let Next.js handle JSX transformation |
|
|
179
|
-
| `plugins` | `[{ "name": "next" }]` | Next.js TypeScript plugin |
|
|
236
|
+
Add narrowing / guards rather than relaxing these options in downstream configs.
|
|
180
237
|
|
|
181
|
-
##
|
|
238
|
+
## Compatibility
|
|
182
239
|
|
|
183
|
-
|
|
240
|
+
| Ecosystem | Works with | Notes |
|
|
241
|
+
| ----------- | ------------------------ | ------------------------------------------------- |
|
|
242
|
+
| TypeScript | `>= 5.0` | Needed for `moduleResolution: "bundler"`. |
|
|
243
|
+
| Vite | 5.x, 6.x | Pairs with `bundler` resolution; no extra config. |
|
|
244
|
+
| Turbopack | Current Next.js releases | Pairs with `next.json`. |
|
|
245
|
+
| webpack | 5.x | Use with `ts-loader` or `babel-loader`. |
|
|
246
|
+
| esbuild | `>= 0.19` | Requires `isolatedModules` (already enabled). |
|
|
247
|
+
| swc / Babel | Current | Honour `isolatedModules`; no decorator metadata. |
|
|
248
|
+
| React | 17, 18, 19 | `react.json` ships `react-jsx` (no React import). |
|
|
249
|
+
| Next.js | 13+ (App Router) | `next.json` wires the `next` TS plugin. |
|
|
250
|
+
| Node.js | Any LTS | This package is configuration only — no runtime. |
|
|
184
251
|
|
|
185
|
-
|
|
186
|
-
{
|
|
187
|
-
"compilerOptions": {
|
|
188
|
-
"allowJs": true,
|
|
189
|
-
"esModuleInterop": true,
|
|
190
|
-
"isolatedModules": true,
|
|
191
|
-
"lib": ["DOM", "DOM.Iterable", "ESNext"],
|
|
192
|
-
"module": "ESNext",
|
|
193
|
-
"moduleResolution": "bundler",
|
|
194
|
-
"noEmit": true,
|
|
195
|
-
"resolveJsonModule": true,
|
|
196
|
-
"skipLibCheck": true,
|
|
197
|
-
"strict": true,
|
|
198
|
-
"target": "ESNext"
|
|
199
|
-
}
|
|
200
|
-
}
|
|
201
|
-
```
|
|
252
|
+
## Troubleshooting
|
|
202
253
|
|
|
203
|
-
###
|
|
254
|
+
### Cannot find preset / "Cannot find module @codefast/typescript-config/..."
|
|
204
255
|
|
|
205
|
-
|
|
256
|
+
Ensure the package is installed as a dev dependency in the consumer project and that your `tsconfig.json` extends the full file name:
|
|
257
|
+
|
|
258
|
+
```json5
|
|
206
259
|
{
|
|
207
|
-
|
|
208
|
-
"compilerOptions": {
|
|
209
|
-
"lib": ["ESNext"]
|
|
210
|
-
}
|
|
260
|
+
extends: "@codefast/typescript-config/react.json",
|
|
211
261
|
}
|
|
212
262
|
```
|
|
213
263
|
|
|
214
|
-
|
|
264
|
+
Don't drop the `.json` extension — TypeScript resolves these as files, not packages.
|
|
215
265
|
|
|
216
|
-
|
|
217
|
-
{
|
|
218
|
-
"extends": "./base.json",
|
|
219
|
-
"compilerOptions": {
|
|
220
|
-
"jsx": "react-jsx"
|
|
221
|
-
}
|
|
222
|
-
}
|
|
223
|
-
```
|
|
266
|
+
### Conflicting `lib` settings
|
|
224
267
|
|
|
225
|
-
|
|
268
|
+
If you're using `library.json` but need DOM types (e.g. a React-targeting package), override `lib` locally:
|
|
226
269
|
|
|
227
|
-
```
|
|
270
|
+
```json5
|
|
228
271
|
{
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
"
|
|
232
|
-
|
|
233
|
-
"plugins": [{ "name": "next" }]
|
|
234
|
-
}
|
|
272
|
+
extends: "@codefast/typescript-config/library.json",
|
|
273
|
+
compilerOptions: {
|
|
274
|
+
lib: ["DOM", "DOM.Iterable", "ESNext"],
|
|
275
|
+
},
|
|
235
276
|
}
|
|
236
277
|
```
|
|
237
278
|
|
|
238
|
-
|
|
279
|
+
### "Cannot use JSX unless the '--jsx' flag is provided"
|
|
239
280
|
|
|
240
|
-
|
|
241
|
-
| ---------- | --------------- | ------------------------------------ |
|
|
242
|
-
| TypeScript | 5.0.0 | Required |
|
|
243
|
-
| Node.js | 24.0.0 | Required |
|
|
244
|
-
| React | 18.0.0+ | When using `react.json` |
|
|
245
|
-
| Next.js | 14.0.0+ | When using `next.json` |
|
|
246
|
-
| Vite | 5.0.0+ | Works with bundler module resolution |
|
|
247
|
-
| Turbopack | Any | Works with bundler module resolution |
|
|
248
|
-
| esbuild | 0.19+ | Works with bundler module resolution |
|
|
281
|
+
The base preset does not set `jsx` — switch to `react.json` or `next.json` depending on your bundler:
|
|
249
282
|
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
283
|
+
```json5
|
|
284
|
+
{ extends: "@codefast/typescript-config/react.json" }
|
|
285
|
+
```
|
|
253
286
|
|
|
254
|
-
|
|
287
|
+
or
|
|
255
288
|
|
|
256
|
-
```
|
|
257
|
-
|
|
289
|
+
```json5
|
|
290
|
+
{ extends: "@codefast/typescript-config/next.json" }
|
|
258
291
|
```
|
|
259
292
|
|
|
260
|
-
###
|
|
293
|
+
### `noUncheckedIndexedAccess` errors you don't want
|
|
261
294
|
|
|
262
|
-
If you
|
|
295
|
+
If you truly don't want `T | undefined` for indexed access in a specific project (e.g. generated code), override it locally:
|
|
263
296
|
|
|
264
|
-
```
|
|
297
|
+
```json5
|
|
265
298
|
{
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
}
|
|
299
|
+
extends: "@codefast/typescript-config/base.json",
|
|
300
|
+
compilerOptions: {
|
|
301
|
+
noUncheckedIndexedAccess: false,
|
|
302
|
+
},
|
|
270
303
|
}
|
|
271
304
|
```
|
|
272
305
|
|
|
273
|
-
|
|
306
|
+
Prefer narrowing (`if (value === undefined) return;` or `value?.foo`) to disabling the check.
|
|
274
307
|
|
|
275
|
-
|
|
308
|
+
### Emitting output despite `noEmit: true`
|
|
276
309
|
|
|
277
|
-
|
|
310
|
+
The preset sets `noEmit: true` because the assumption is a separate bundler (tsdown, Vite, Next.js…) does the emitting. For a tsc-driven build, override in a dedicated `tsconfig.build.json`:
|
|
311
|
+
|
|
312
|
+
```json5
|
|
278
313
|
{
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
314
|
+
extends: "@codefast/typescript-config/library.json",
|
|
315
|
+
compilerOptions: {
|
|
316
|
+
noEmit: false,
|
|
317
|
+
declaration: true,
|
|
318
|
+
outDir: "./dist",
|
|
319
|
+
},
|
|
320
|
+
include: ["src/**/*"],
|
|
321
|
+
exclude: ["**/*.test.ts", "**/*.test.tsx"],
|
|
283
322
|
}
|
|
284
323
|
```
|
|
285
324
|
|
|
286
|
-
### Incremental build
|
|
325
|
+
### Incremental build cache gets out of sync (Next.js)
|
|
287
326
|
|
|
288
|
-
|
|
327
|
+
Delete the stale `.tsbuildinfo` and rebuild:
|
|
289
328
|
|
|
290
329
|
```bash
|
|
291
|
-
rm -f tsconfig.tsbuildinfo
|
|
330
|
+
rm -f tsconfig.tsbuildinfo .next/types
|
|
292
331
|
pnpm build
|
|
293
332
|
```
|
|
294
333
|
|
|
295
334
|
## Contributing
|
|
296
335
|
|
|
297
|
-
|
|
336
|
+
Contributions are welcome. See the repository-root [contributing guide](../../README.md#contributing).
|
|
298
337
|
|
|
299
|
-
|
|
338
|
+
This package is configuration-only — there's nothing to build or test in isolation. Changes should be validated by running the full repo checks:
|
|
300
339
|
|
|
301
340
|
```bash
|
|
302
|
-
#
|
|
303
|
-
pnpm
|
|
341
|
+
# type-check every package
|
|
342
|
+
pnpm check-types
|
|
304
343
|
|
|
305
|
-
#
|
|
344
|
+
# lint & format
|
|
306
345
|
pnpm lint
|
|
307
346
|
pnpm format
|
|
308
347
|
```
|
|
309
348
|
|
|
310
349
|
## License
|
|
311
350
|
|
|
312
|
-
|
|
351
|
+
MIT — see the repository-level [LICENSE](../../LICENSE).
|
|
313
352
|
|
|
314
353
|
## Changelog
|
|
315
354
|
|
|
316
|
-
See [CHANGELOG.md](./CHANGELOG.md) for
|
|
355
|
+
See [CHANGELOG.md](./CHANGELOG.md) for the full version history.
|