@sicoti/tsconfig 1.0.0 → 2.0.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/README.md CHANGED
@@ -1,331 +1,381 @@
1
- # @sicoti/tsconfig
2
-
3
- [![npm version](https://img.shields.io/npm/v/@sicoti/tsconfig.svg?style=flat-square)](https://www.npmjs.com/package/@sicoti/tsconfig)
4
- [![npm downloads](https://img.shields.io/npm/dm/@sicoti/tsconfig.svg?style=flat-square)](https://www.npmjs.com/package/@sicoti/tsconfig)
5
- [![TypeScript](https://img.shields.io/badge/TypeScript-%3E%3D5.9-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
6
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
7
-
8
- > Shareable TypeScript configuration presets with strict type checking for modern projects.
9
-
10
- ## Features
11
-
12
- - 🔒 **Maximum Type Safety** — Strict mode plus additional safety checks beyond `strict: true`
13
- - 📦 **Environment-Specific Presets** — Optimized configs for Next.js, NestJS, React libraries, and Bun
14
- - 🎯 **Zero Configuration** — Works out of the box with sensible defaults
15
- - 🔧 **Fully Extensible** — Easy to override any setting for your specific needs
16
- - 📚 **Well Documented** — Clear comments explaining every option
17
-
18
- ## 📦 Installation
19
-
20
- ```bash
21
- # npm
22
- npm install -D @sicoti/tsconfig typescript
23
-
24
- # yarn
25
- yarn add -D @sicoti/tsconfig typescript
26
-
27
- # pnpm
28
- pnpm add -D @sicoti/tsconfig typescript
29
-
30
- # bun
31
- bun add -D @sicoti/tsconfig typescript
32
- ```
33
-
34
- ## 🚀 Quick Start
35
-
36
- Choose the preset that matches your project type and extend it in your `tsconfig.json`:
37
-
38
- ### Next.js Applications
39
-
40
- ```jsonc
41
- {
42
- "extends": "@sicoti/tsconfig/nextjs.json",
43
- "compilerOptions": {
44
- "baseUrl": ".",
45
- "paths": {
46
- "@/*": ["./src/*"]
47
- }
48
- },
49
- "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
50
- "exclude": ["node_modules"]
51
- }
52
- ```
53
-
54
- ### NestJS Applications
55
-
56
- ```jsonc
57
- {
58
- "extends": "@sicoti/tsconfig/nestjs.json",
59
- "compilerOptions": {
60
- "outDir": "./dist",
61
- "baseUrl": ".",
62
- "paths": {
63
- "@/*": ["./src/*"]
64
- }
65
- },
66
- "include": ["src/**/*"],
67
- "exclude": ["node_modules", "dist"]
68
- }
69
- ```
70
-
71
- ### React Component Libraries
72
-
73
- ```jsonc
74
- {
75
- "extends": "@sicoti/tsconfig/react-library.json",
76
- "compilerOptions": {
77
- "outDir": "./dist",
78
- "rootDir": "./src",
79
- "baseUrl": ".",
80
- "paths": {
81
- "@/*": ["./src/*"]
82
- }
83
- },
84
- "include": ["src/**/*"],
85
- "exclude": ["dist", "node_modules"]
86
- }
87
- ```
88
-
89
- ### Bun Packages & CLI Tools
90
-
91
- ```jsonc
92
- {
93
- "extends": "@sicoti/tsconfig/bun.json",
94
- "compilerOptions": {
95
- "outDir": "./dist",
96
- "rootDir": "./src",
97
- "baseUrl": ".",
98
- "paths": {
99
- "@/*": ["./src/*"]
100
- }
101
- },
102
- "include": ["src/**/*"],
103
- "exclude": ["dist", "node_modules"]
104
- }
105
- ```
106
-
107
- ## 📋 Available Presets
108
-
109
- | Preset | Use Case | Key Features |
110
- |:-------|:---------|:-------------|
111
- | `nextjs.json` | Next.js apps (App Router / Pages Router) | `jsx: preserve`, `noEmit`, Next.js plugin |
112
- | `nestjs.json` | NestJS backend applications | Decorator metadata, source maps, DI support |
113
- | `react-library.json` | React component libraries | `jsx: react-jsx`, declaration files, source maps |
114
- | `bun.json` | Bun runtime packages & CLI tools | Declaration files, optimized for Bun bundler |
115
- | `base.json` | ⚠️ Internal foundation (not for direct use) | Universal strict settings |
116
-
117
- ## 🔒 Strict Type Checking
118
-
119
- All presets inherit from `base.json` which enables maximum type safety:
120
-
121
- ### Enabled by `strict: true`
122
-
123
- | Option | Description |
124
- |:-------|:------------|
125
- | `strictNullChecks` | Check null/undefined assignments |
126
- | `strictFunctionTypes` | Strict function type checking |
127
- | `strictBindCallApply` | Type checking for bind/call/apply |
128
- | `strictPropertyInitialization` | Ensure class properties are initialized |
129
- | `noImplicitThis` | Error on implicit 'this' types |
130
- | `noImplicitAny` | Error on implicit 'any' types |
131
- | `alwaysStrict` | Emit "use strict" in all files |
132
- | `useUnknownInCatchVariables` | Use 'unknown' instead of 'any' in catch |
133
-
134
- ### Additional Safety Checks (Not in `strict: true`)
135
-
136
- | Option | Description |
137
- |:-------|:------------|
138
- | `noUnusedLocals` | Error on unused local variables |
139
- | `noUnusedParameters` | Error on unused function parameters |
140
- | `noImplicitReturns` | Error when not all paths return a value |
141
- | `noFallthroughCasesInSwitch` | Error on switch case fall-through |
142
- | `allowUnreachableCode` | Error on unreachable code |
143
- | `noUncheckedIndexedAccess` | Add `undefined` to index signature results |
144
- | `exactOptionalPropertyTypes` | Distinguish between `undefined` and missing |
145
- | `noPropertyAccessFromIndexSignature` | Require bracket notation for index access |
146
- | `noImplicitOverride` | Require 'override' keyword for overrides |
147
- | `noUncheckedSideEffectImports` | Validate side-effect imports exist |
148
-
149
- ## 💡 Why These Checks Matter
150
-
151
- ### `noUncheckedIndexedAccess`
152
-
153
- ```typescript
154
- // Without: No error, crashes at runtime
155
- const users: User[] = [];
156
- const first = users[0]; // Type: User (WRONG!)
157
- first.name; // 💥 Runtime error: Cannot read property 'name' of undefined
158
-
159
- // ✅ With: Compiler catches it
160
- const first = users[0]; // Type: User | undefined
161
- if (first) {
162
- first.name; // Safe access
163
- }
164
- ```
165
-
166
- ### `noFallthroughCasesInSwitch`
167
-
168
- ```typescript
169
- // Without: Silent fall-through bug
170
- switch (action) {
171
- case "login":
172
- login();
173
- // Oops! Falls through to logout!
174
- case "logout":
175
- logout();
176
- break;
177
- }
178
-
179
- // With: TS7029 error prevents the bug
180
- ```
181
-
182
- ### `exactOptionalPropertyTypes`
183
-
184
- ```typescript
185
- interface Config {
186
- cache?: { ttl: number };
187
- }
188
-
189
- // Without: Both accepted but have different semantics
190
- setConfig({}); // OK - cache is missing
191
- setConfig({ cache: undefined }); // OK - but this explicitly sets cache to undefined!
192
-
193
- // With: Explicit undefined is an error
194
- // TS2379: Type 'undefined' is not assignable to type '{ ttl: number }'
195
- ```
196
-
197
- ### Why `strict: true` Alone Is Not Enough
198
-
199
- Many developers assume that `"strict": true` enables all TypeScript safety checks. **This is a common misconception.** The `strict` flag only enables 8 specific checks, leaving many critical safety features disabled by default.
200
-
201
- ```typescript
202
- // This code compiles with ONLY strict: true
203
-
204
- // 1. Unused variables? No error.
205
- const unusedVar = "I'm never used";
206
-
207
- // 2. Array access without bounds checking? No error.
208
- const users: string[] = [];
209
- const first = users[0]; // Type: string (but it's actually undefined!)
210
- first.toUpperCase(); // 💥 Runtime crash!
211
-
212
- // 3. Switch fall-through? No error.
213
- function handle(action: "save" | "delete") {
214
- switch (action) {
215
- case "save":
216
- save();
217
- // Oops! Falls through to delete!
218
- case "delete":
219
- deleteAll(); // 💥 Unintended deletion!
220
- }
221
- }
222
-
223
- // 4. Missing return in some branches? No error.
224
- function getValue(condition: boolean): string {
225
- if (condition) {
226
- return "value";
227
- }
228
- // 💥 Returns undefined, but TypeScript says it returns string!
229
- }
230
- ```
231
-
232
- ```typescript
233
- // ✅ With @sicoti/tsconfig - ALL of these are caught at compile time!
234
-
235
- // 1. TS6133: 'unusedVar' is declared but never used
236
- const unusedVar = "I'm never used";
237
-
238
- // 2. TS18048: 'first' is possibly 'undefined'
239
- const users: string[] = [];
240
- const first = users[0]; // Type: string | undefined
241
- if (first) {
242
- first.toUpperCase(); // ✓ Safe!
243
- }
244
-
245
- // 3. TS7029: Fallthrough case in switch
246
- function handle(action: "save" | "delete") {
247
- switch (action) {
248
- case "save":
249
- save();
250
- break; // Required!
251
- case "delete":
252
- deleteAll();
253
- }
254
- }
255
-
256
- // 4. TS7030: Not all code paths return a value
257
- function getValue(condition: boolean): string {
258
- if (condition) {
259
- return "value";
260
- }
261
- return "default"; // ✓ Required!
262
- }
263
- ```
264
-
265
- **Bottom line:** `strict: true` is just the starting point. This package enables **10+ additional checks** that catch real bugs before they reach production.
266
-
267
- ## 🏗️ Architecture
268
-
269
- ```plaintext
270
- @sicoti/tsconfig/
271
- ├── base.json ← Foundation (DO NOT extend directly)
272
- │ ├── nextjs.json ← Next.js applications
273
- │ ├── nestjs.json ← NestJS applications
274
- │ ├── bun.json ← Bun runtime packages
275
- │ └── react-library.json ← React component libraries
276
- ```
277
-
278
- ### Design Philosophy
279
-
280
- **`base.json` includes:**
281
-
282
- - Universal strict type checking settings
283
- - Modern ES module configuration
284
- - Code quality checks (unused code, control flow)
285
- - Import safety validations
286
-
287
- **`base.json` intentionally excludes:**
288
-
289
- - `lib` (DOM, ESNext) — Varies by runtime environment
290
- - `jsx` settings — Only for React-based projects
291
- - `sourceMap`, `declaration` Build output varies by project
292
- - `emitDecoratorMetadata` Only for NestJS/decorator-based DI
293
-
294
- ## 🔧 Customization
295
-
296
- You can override any setting in your project's `tsconfig.json`:
297
-
298
- ```jsonc
299
- {
300
- "extends": "@sicoti/tsconfig/nextjs.json",
301
- "compilerOptions": {
302
- // Override specific settings
303
- "noUncheckedIndexedAccess": false, // Disable if too strict for your codebase
304
- "baseUrl": ".",
305
- "paths": {
306
- "@/*": ["./src/*"],
307
- "@components/*": ["./src/components/*"]
308
- }
309
- }
310
- }
311
- ```
312
-
313
- ## 🤝 Contributing
314
-
315
- Contributions are welcome! Please feel free to submit a Pull Request.
316
-
317
- 1. Fork the repository
318
- 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
319
- 3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
320
- 4. Push to the branch (`git push origin feature/amazing-feature`)
321
- 5. Open a Pull Request
322
-
323
- ## 📄 License
324
-
325
- [MIT](LICENSE) © [SICOTI Team](https://github.com/SICOTI-Peru)
326
-
327
- ---
328
-
329
- <p align="center">
330
- Made with ❤️ by the <a href="https://github.com/SICOTI-Peru">SICOTI Team</a>
331
- </p>
1
+ # @sicoti/tsconfig
2
+
3
+ [![npm version](https://img.shields.io/npm/v/@sicoti/tsconfig.svg?style=flat-square)](https://www.npmjs.com/package/@sicoti/tsconfig)
4
+ [![npm downloads](https://img.shields.io/npm/dm/@sicoti/tsconfig.svg?style=flat-square)](https://www.npmjs.com/package/@sicoti/tsconfig)
5
+ [![TypeScript](https://img.shields.io/badge/TypeScript-6%20%7C%207-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
7
+
8
+ > Centralized, shareable TypeScript configuration presets that enforce maximum type safety and best practices for modern JavaScript projects. Built for Next.js, NestJS, React libraries, and Bun with zero configuration.
9
+
10
+ ## 📋 Table of Contents
11
+
12
+ - [🚀 Features](#-features)
13
+ - [📦 Installation](#-installation)
14
+ - [🔍 Requirements](#-requirements)
15
+ - [⚡ Quick Start](#-quick-start)
16
+ - [Next.js Applications](#nextjs-applications)
17
+ - [NestJS Applications](#nestjs-applications)
18
+ - [Bundled React Component Libraries](#bundled-react-component-libraries)
19
+ - [Bun Packages & CLI Tools](#bun-packages--cli-tools)
20
+ - [📋 Available Presets](#-available-presets)
21
+ - [🔒 Strict Type Checking](#-strict-type-checking)
22
+ - [Enabled by `strict: true`](#enabled-by-strict-true)
23
+ - [Additional Safety Checks (Not in `strict: true`)](#additional-safety-checks-not-in-strict-true)
24
+ - [❓ Why These Checks Matter](#-why-these-checks-matter)
25
+ - [`noUncheckedIndexedAccess`](#nouncheckedindexedaccess)
26
+ - [`noFallthroughCasesInSwitch`](#nofallthroughcasesinswitch)
27
+ - [`exactOptionalPropertyTypes`](#exactoptionalpropertytypes)
28
+ - [Why `strict: true` Alone Is Not Enough](#why-strict-true-alone-is-not-enough)
29
+ - [🏗️ Architecture](#️-architecture)
30
+ - [Design Philosophy](#design-philosophy)
31
+ - [🔧 Customization](#-customization)
32
+ - [📝 Changelog](#-changelog)
33
+ - [🤝 Contributing](#-contributing)
34
+ - [📄 License](#-license)
35
+
36
+ ## Features
37
+
38
+ - 🔒 **Maximum Type Safety** — Strict mode plus additional safety checks beyond `strict: true`
39
+ - 📦 **Environment-Specific Presets** — Optimized configs for Next.js, NestJS, Node/shared libraries, React libraries, and Bun
40
+ - 🎯 **Zero Configuration** — Works out of the box with sensible defaults
41
+ - 🔧 **Fully Extensible** — Easy to override any setting for your specific needs
42
+ - 📚 **Well Documented** — Clear comments explaining every option
43
+
44
+ ## 📦 Installation
45
+
46
+ ```bash
47
+ # npm
48
+ npm install -D @sicoti/tsconfig typescript
49
+
50
+ # yarn
51
+ yarn add -D @sicoti/tsconfig typescript
52
+
53
+ # pnpm
54
+ pnpm add -D @sicoti/tsconfig typescript
55
+
56
+ # bun
57
+ bun add -D @sicoti/tsconfig typescript
58
+ ```
59
+
60
+ ## 🔍 Requirements
61
+
62
+ - **TypeScript**: `>= 6 < 8` (consumer fixtures are compiled with TypeScript 6 and TypeScript 7)
63
+ - **Node.js**: `>= 24.0.0`
64
+ - **Package Manager**: npm, yarn, pnpm, or bun
65
+
66
+ ## ⚡ Quick Start
67
+
68
+ Choose the preset that matches your project type and extend it in your `tsconfig.json`:
69
+
70
+ ### Next.js Applications
71
+
72
+ ```jsonc
73
+ {
74
+ "extends": "@sicoti/tsconfig/nextjs.json",
75
+ "compilerOptions": {
76
+ "paths": {
77
+ "@/*": ["./src/*"]
78
+ }
79
+ },
80
+ "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
81
+ "exclude": ["node_modules"]
82
+ }
83
+ ```
84
+
85
+ ### NestJS Applications
86
+
87
+ ```jsonc
88
+ {
89
+ "extends": "@sicoti/tsconfig/nestjs.json",
90
+ "compilerOptions": {
91
+ "outDir": "./dist",
92
+ "paths": {
93
+ "@/*": ["./src/*"]
94
+ }
95
+ },
96
+ "include": ["src/**/*"],
97
+ "exclude": ["node_modules", "dist"]
98
+ }
99
+ ```
100
+
101
+ ### Bundled React Component Libraries
102
+
103
+ `react-library.json` models source that is bundled before publication (for
104
+ example with tsdown, Rolldown, Vite library mode, or an equivalent build tool).
105
+ TypeScript typechecks the source while the bundler owns JavaScript and declaration
106
+ output.
107
+
108
+ ```jsonc
109
+ {
110
+ "extends": "@sicoti/tsconfig/react-library.json",
111
+ "compilerOptions": {
112
+ "paths": {
113
+ "@/*": ["./src/*"]
114
+ }
115
+ },
116
+ "include": ["src/**/*"],
117
+ "exclude": ["dist", "node_modules"]
118
+ }
119
+ ```
120
+
121
+ ### Bun Packages & CLI Tools
122
+
123
+ ```jsonc
124
+ {
125
+ "extends": "@sicoti/tsconfig/bun.json",
126
+ "compilerOptions": {
127
+ "paths": {
128
+ "@/*": ["./src/*"]
129
+ }
130
+ },
131
+ "include": ["src/**/*"],
132
+ "exclude": ["dist", "node_modules"]
133
+ }
134
+ ```
135
+
136
+ ### Node / Shared Libraries
137
+
138
+ `node.json` models direct Node ESM execution with `NodeNext` resolution and
139
+ declaration emit. Relative ESM imports therefore use the runtime extension that
140
+ Node will execute (for example `./value.js` from TypeScript source):
141
+
142
+ ```jsonc
143
+ {
144
+ "extends": "@sicoti/tsconfig/node.json",
145
+ "include": ["src/**/*"]
146
+ }
147
+ ```
148
+
149
+ ## 📋 Available Presets
150
+
151
+ | Preset | Use Case | Key Features |
152
+ | :------- | :--------- | :------------- |
153
+ | `nextjs.json` | Next.js apps (App Router / Pages Router) | `jsx: preserve`, `noEmit`, Next.js plugin |
154
+ | `nestjs.json` | NestJS backend applications executed by Node | `NodeNext`, decorator metadata, source maps, DI support |
155
+ | `node.json` | Node ESM packages/libraries that emit declarations | `NodeNext`, Node types, declaration + source-map emit |
156
+ | `react-library.json` | React libraries bundled before publication | `module: Preserve`, bundler resolution, `jsx: react-jsx`, `noEmit` |
157
+ | `bun.json` | Bun-native packages & CLI tools | `module: Preserve`, bundler resolution, `.ts` imports, `noEmit` |
158
+ | `base.json` | ⚠️ Internal foundation (not for direct use) | Universal strict settings |
159
+
160
+ ## 🔒 Strict Type Checking
161
+
162
+ All presets inherit from `base.json` which enables maximum type safety:
163
+
164
+ ### Enabled by `strict: true`
165
+
166
+ | Option | Description |
167
+ | :------- | :------------ |
168
+ | `strictNullChecks` | Check null/undefined assignments |
169
+ | `strictFunctionTypes` | Strict function type checking |
170
+ | `strictBindCallApply` | Type checking for bind/call/apply |
171
+ | `strictPropertyInitialization` | Ensure class properties are initialized |
172
+ | `noImplicitThis` | Error on implicit 'this' types |
173
+ | `noImplicitAny` | Error on implicit 'any' types |
174
+ | `alwaysStrict` | Emit "use strict" in all files |
175
+ | `useUnknownInCatchVariables` | Use 'unknown' instead of 'any' in catch |
176
+
177
+ ### Additional Safety Checks (Not in `strict: true`)
178
+
179
+ | Option | Description |
180
+ | :------- | :------------ |
181
+ | `noUnusedLocals` | Error on unused local variables |
182
+ | `noUnusedParameters` | Error on unused function parameters |
183
+ | `noImplicitReturns` | Error when not all paths return a value |
184
+ | `noFallthroughCasesInSwitch` | Error on switch case fall-through |
185
+ | `allowUnreachableCode` | Error on unreachable code |
186
+ | `noUncheckedIndexedAccess` | Add `undefined` to index signature results |
187
+ | `noPropertyAccessFromIndexSignature` | Require bracket notation for index access |
188
+ | `noImplicitOverride` | Require 'override' keyword for overrides |
189
+ | `noUncheckedSideEffectImports` | Validate side-effect imports exist |
190
+
191
+ `exactOptionalPropertyTypes` is deliberately `false` in the shared baseline for
192
+ the current NestJS/Prisma/React compatibility boundary. This does not relax
193
+ `strict`, `noUncheckedIndexedAccess`, or `noPropertyAccessFromIndexSignature`.
194
+
195
+ ## 💡 Why These Checks Matter
196
+
197
+ ### `noUncheckedIndexedAccess`
198
+
199
+ ```typescript
200
+ // ❌ Without: No error, crashes at runtime
201
+ const users: User[] = [];
202
+ const first = users[0]; // Type: User (WRONG!)
203
+ first.name; // 💥 Runtime error: Cannot read property 'name' of undefined
204
+
205
+ // With: Compiler catches it
206
+ const first = users[0]; // Type: User | undefined
207
+ if (first) {
208
+ first.name; // Safe access
209
+ }
210
+ ```
211
+
212
+ ### `noFallthroughCasesInSwitch`
213
+
214
+ ```typescript
215
+ // ❌ Without: Silent fall-through bug
216
+ switch (action) {
217
+ case "login":
218
+ login();
219
+ // Oops! Falls through to logout!
220
+ case "logout":
221
+ logout();
222
+ break;
223
+ }
224
+
225
+ // With: TS7029 error prevents the bug
226
+ ```
227
+
228
+ ### `exactOptionalPropertyTypes`
229
+
230
+ ```typescript
231
+ interface Config {
232
+ cache?: { ttl: number };
233
+ }
234
+
235
+ // Without: Both accepted but have different semantics
236
+ setConfig({}); // OK - cache is missing
237
+ setConfig({ cache: undefined }); // OK - but this explicitly sets cache to undefined!
238
+
239
+ // ✅ With: Explicit undefined is an error
240
+ // TS2379: Type 'undefined' is not assignable to type '{ ttl: number }'
241
+ ```
242
+
243
+ ### Why `strict: true` Alone Is Not Enough
244
+
245
+ Many developers assume that `"strict": true` enables all TypeScript safety checks. **This is a common misconception.** The `strict` flag only enables 8 specific checks, leaving many critical safety features disabled by default.
246
+
247
+ ```typescript
248
+ // ❌ This code compiles with ONLY strict: true
249
+
250
+ // 1. Unused variables? No error.
251
+ const unusedVar = "I'm never used";
252
+
253
+ // 2. Array access without bounds checking? No error.
254
+ const users: string[] = [];
255
+ const first = users[0]; // Type: string (but it's actually undefined!)
256
+ first.toUpperCase(); // 💥 Runtime crash!
257
+
258
+ // 3. Switch fall-through? No error.
259
+ function handle(action: "save" | "delete") {
260
+ switch (action) {
261
+ case "save":
262
+ save();
263
+ // Oops! Falls through to delete!
264
+ case "delete":
265
+ deleteAll(); // 💥 Unintended deletion!
266
+ }
267
+ }
268
+
269
+ // 4. Missing return in some branches? No error.
270
+ function getValue(condition: boolean): string {
271
+ if (condition) {
272
+ return "value";
273
+ }
274
+ // 💥 Returns undefined, but TypeScript says it returns string!
275
+ }
276
+ ```
277
+
278
+ ```typescript
279
+ // ✅ With @sicoti/tsconfig - ALL of these are caught at compile time!
280
+
281
+ // 1. TS6133: 'unusedVar' is declared but never used
282
+ const unusedVar = "I'm never used";
283
+
284
+ // 2. TS18048: 'first' is possibly 'undefined'
285
+ const users: string[] = [];
286
+ const first = users[0]; // Type: string | undefined
287
+ if (first) {
288
+ first.toUpperCase(); // ✓ Safe!
289
+ }
290
+
291
+ // 3. TS7029: Fallthrough case in switch
292
+ function handle(action: "save" | "delete") {
293
+ switch (action) {
294
+ case "save":
295
+ save();
296
+ break; // Required!
297
+ case "delete":
298
+ deleteAll();
299
+ }
300
+ }
301
+
302
+ // 4. TS7030: Not all code paths return a value
303
+ function getValue(condition: boolean): string {
304
+ if (condition) {
305
+ return "value";
306
+ }
307
+ return "default"; // ✓ Required!
308
+ }
309
+ ```
310
+
311
+ **Bottom line:** `strict: true` is just the starting point. This package enables **10+ additional checks** that catch real bugs before they reach production.
312
+
313
+ ## 🏗️ Architecture
314
+
315
+ ```mermaid
316
+ flowchart TD
317
+ base["base.json<br/>Foundation (DO NOT extend directly)<br/>Universal strict settings"] --> nextjs["nextjs.json<br/>Next.js applications<br/>jsx: preserve, noEmit, Next.js plugin"]
318
+ base --> nestjs["nestjs.json<br/>NestJS on Node<br/>NodeNext, decorators, source maps"]
319
+ base --> node["node.json<br/>Direct Node ESM<br/>NodeNext, declaration emit"]
320
+ base --> bun["bun.json<br/>Bun-native runtime<br/>Preserve, bundler resolution, noEmit"]
321
+ base --> reactlib["react-library.json<br/>Bundled React libraries<br/>Preserve, bundler resolution, noEmit"]
322
+ ```
323
+
324
+ ### Design Philosophy
325
+
326
+ **`base.json` includes:**
327
+
328
+ - Universal strict type checking settings
329
+ - Runtime-neutral module hygiene
330
+ - Code quality checks (unused code, control flow)
331
+ - Import safety validations
332
+
333
+ **`base.json` intentionally excludes:**
334
+
335
+ - `lib` (DOM, ESNext) — Varies by runtime environment
336
+ - `target`, `module`, `moduleResolution` — Must model the actual runtime/bundler
337
+ - `jsx` settings — Only for React-based projects
338
+ - `sourceMap`, `declaration` — Build output varies by project
339
+ - `emitDecoratorMetadata` — Only for NestJS/decorator-based DI
340
+
341
+ ## 🔧 Customization
342
+
343
+ You can override any setting in your project's `tsconfig.json`:
344
+
345
+ ```jsonc
346
+ {
347
+ "extends": "@sicoti/tsconfig/nextjs.json",
348
+ "compilerOptions": {
349
+ // Override specific settings
350
+ "noUncheckedIndexedAccess": false, // Disable if too strict for your codebase
351
+ "paths": {
352
+ "@/*": ["./src/*"],
353
+ "@components/*": ["./src/components/*"]
354
+ }
355
+ }
356
+ }
357
+ ```
358
+
359
+ ## 📝 Changelog
360
+
361
+ See [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.
362
+
363
+ ## 🤝 Contributing
364
+
365
+ Contributions are welcome! Please feel free to submit a Pull Request.
366
+
367
+ 1. Fork the repository
368
+ 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
369
+ 3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
370
+ 4. Push to the branch (`git push origin feature/amazing-feature`)
371
+ 5. Open a Pull Request
372
+
373
+ ## 📄 License
374
+
375
+ [MIT](LICENSE) © [SICOTI Team](https://github.com/SICOTI-Peru)
376
+
377
+ ---
378
+
379
+ <p align="center">
380
+ Made with ❤️ by the <a href="https://github.com/SICOTI-Peru">SICOTI Team</a>
381
+ </p>