@m0n0lab/ts-configs

Shared TypeScript configurations for modern web and Node.js projects. Battle-tested, production-ready, and maximum type safety.

Features

• 🚀 Production ready
• 📘 Well documented

Installation

npm

npm install @m0n0lab/ts-configs

pnpm

pnpm add @m0n0lab/ts-configs

JSR

npx jsr add @m0n0lab/ts-configs

Configuration Hierarchy

tsconfig.base.json (platform-agnostic foundation)
├── tsconfig.web.base.json ✅
│   ├── tsconfig.web.lib.json ✅
│   └── tsconfig.web.app.json ✅
└── tsconfig.node.base.json (coming soon)
    ├── tsconfig.node.lib.json (coming soon)
    └── tsconfig.node.app.json (coming soon)

Available Configurations

tsconfig.base.json

Platform-agnostic foundation config with maximum type safety and performance optimizations.

Includes:

• ✅ Language & Target: ES2022 output, ES2024 API types
• ✅ Maximum Strictness: 18 strict flags (12 compiler options)
• ✅ ESM Interop: Modern module handling with bundler compatibility
• ✅ Performance: Incremental compilation and project references support

Does NOT include:

• ❌ Platform-specific module settings (module, moduleResolution)
• ❌ Runtime library types (DOM, Node APIs)
• ❌ Build output configuration (declaration, outDir, etc.)

Usage:

{
    "extends": "@m0n0lab/ts-configs/tsconfig.base.json",
    "compilerOptions": {
        // Add platform-specific settings here
        "module": "preserve", // or "NodeNext" for Node.js
        "moduleResolution": "bundler" // or omit for Node.js
    }
}

tsconfig.web.base.json

Base configuration for web/browser projects with modern bundler support and DOM types.

Extends: tsconfig.base.json

Adds:

• ✅ Browser Environment: lib: ["ES2024", "DOM", "DOM.Iterable"]
• ✅ Module System: module: "preserve", moduleResolution: "bundler"
• ✅ React JSX: jsx: "react-jsx" for React projects

Usage:

{
    "extends": "@m0n0lab/ts-configs/tsconfig.web.base.json",
    "compilerOptions": {
        // Override JSX for SolidJS projects
        "jsx": "preserve",
        "jsxImportSource": "solid-js"
    }
}

tsconfig.web.app.json

Configuration for web applications (not libraries). Optimized for bundled, executable apps.

Extends: tsconfig.web.base.json

Adds:

• ✅ No Declaration Files: declaration: false, declarationMap: false (apps don't need .d.ts)
• ✅ Output Settings: noEmit: false, sourceMap: true for debugging
• ✅ Performance: incremental: true for faster rebuilds
• ✅ Mixed Codebases: allowJs: true for JS/TS projects

Usage:

{
    "extends": "@m0n0lab/ts-configs/tsconfig.web.app.json",
    "compilerOptions": {
        // Add app-specific overrides here
    },
    "include": ["src"]
}

tsconfig.web.lib.json

Configuration for web libraries that will be published to npm/JSR. Optimized for React components and reusable web packages.

Extends: tsconfig.web.base.json

Adds:

• ✅ Type Declarations: declaration: true, declarationMap: true for consumers
• ✅ Source Maps: sourceMap: true for debugging published packages
• ✅ Composite Builds: Inherits composite: true for project references
• ✅ Tree-Shaking: Inherits module: "preserve" for optimal bundling

Usage:

{
    "extends": "@m0n0lab/ts-configs/tsconfig.web.lib.json",
    "compilerOptions": {
        "outDir": "./dist",
        "rootDir": "./src"
    },
    "include": ["src/**/*"],
    "exclude": ["**/*.test.*", "**/*.spec.*"]
}

Perfect for:

• React component libraries
• Shared UI components
• Web utilities and hooks
• JSR-published packages

Platform Configs (Coming Soon)

Additional platform-specific configs in development:

• tsconfig.node.base.json: Base for Node.js projects (adds module: "NodeNext")
• tsconfig.node.lib.json: For Node.js libraries
• tsconfig.node.app.json: For Node.js applications

Migration Guide

For Existing Projects

If your project currently extends the base config, migrate to the appropriate platform-specific config:

Before:

{
    "extends": "@m0n0lab/ts-configs/tsconfig.base.json",
    "compilerOptions": {
        "module": "preserve",
        "moduleResolution": "bundler"
    }
}

After (for web applications):

{
    "extends": "@m0n0lab/ts-configs/tsconfig.web.app.json",
    "include": ["src"]
}

After (for web libraries):

{
    "extends": "@m0n0lab/ts-configs/tsconfig.web.lib.json",
    "include": ["src"]
}

For Node.js projects (coming soon):

{
    "extends": "@m0n0lab/ts-configs/tsconfig.node.base.json",
    "compilerOptions": {
        "module": "NodeNext"
    }
}

Handling New Strict Flags

The updated base config includes additional strictness flags that may cause compilation errors:

• noImplicitReturns: All code paths must return a value
• noImplicitOverride: Use override keyword when overriding methods
• allowUnreachableCode: false: No unreachable code allowed
• allowUnusedLabels: false: No unused labels allowed

Temporary override during migration:

{
    "extends": "@m0n0lab/ts-configs/tsconfig.base.json",
    "compilerOptions": {
        // Temporarily disable while fixing issues
        "noImplicitReturns": false,
        "noImplicitOverride": false
    }
}

Configuration Details

Group 1: Language & Target

{
    "target": "ES2022", // Stable runtime target (2 versions back)
    "lib": ["ES2024"], // Modern API types (penultimate version)
    "allowJs": true, // Allow JavaScript files
    "resolveJsonModule": true, // Import JSON files with types
    "moduleDetection": "force" // All files are modules
}

Group 2: Strictness

Maximum type safety with 18 active strict flags (12 compiler options):

• strict: true (enables 7 built-in strict flags)
  • noImplicitAny, noImplicitThis, strictNullChecks
  • strictFunctionTypes, strictBindCallApply, strictPropertyInitialization
  • alwaysStrict
• 11 additional strict checks:
  • noUnusedLocals, noUnusedParameters
  • noFallthroughCasesInSwitch
  • noUncheckedIndexedAccess (array access returns T | undefined)
  • exactOptionalPropertyTypes (respects ? vs | undefined)
  • useUnknownInCatchVariables (catch errors are unknown)
  • noPropertyAccessFromIndexSignature (use bracket notation for index signatures)
  • noImplicitOverride (require override keyword)
  • noImplicitReturns (all code paths must return)
  • allowUnreachableCode: false
  • allowUnusedLabels: false

Group 3: ESM Interop & Isolation

{
    "esModuleInterop": true, // Better CommonJS/ESM interop
    "isolatedModules": true, // Each file can be compiled independently
    "verbatimModuleSyntax": true, // Preserve import/export syntax
    "forceConsistentCasingInFileNames": true // Catch case sensitivity issues
}

Group 4: Performance

{
    "incremental": true, // Cache compilation info for faster rebuilds
    "composite": true, // Enable project references for monorepo
    "skipLibCheck": true // Skip type checking in .d.ts files
}

Best Practices

1. Use platform-specific configs: Use tsconfig.web.app.json for web apps, tsconfig.web.base.json for web libraries (when available)
2. Extend, don't copy: Always extend configs rather than copying options
3. Don't override strict flags: Fix the issues instead (long-term benefit)
4. Enable project references: Use composite: true advantage in monorepos
5. Leverage incremental compilation: The configs enable this for faster rebuilds

References

• Total TypeScript TSConfig Cheat Sheet
• TypeScript Compiler Options
• OpenSpec Proposal: openspec/changes/define-base-tsconfig/

License

MIT