@codefast/typescript-config 0.5.0-canary.4 → 0.5.0-canary.6

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