@forgrit/tsconfig

Shared TypeScript configuration presets for ForGrit projects — base, node, and library. Zero runtime cost; just JSON.

Status: early-access (v0.x). Pre-1.0 releases may include breaking changes in minor bumps until v1.0.0.

Install

npm install --save-dev @forgrit/tsconfig
# or
pnpm add -D @forgrit/tsconfig
# or
yarn add -D @forgrit/tsconfig

Usage

Extend the appropriate preset from your tsconfig.json:

Base preset

For library-agnostic TypeScript projects (frontend + backend + tooling):

{
  "extends": "@forgrit/tsconfig/base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
  },
  "include": ["src/**/*.ts"],
}

Node preset

For Node.js projects that need @types/node:

{
  "extends": "@forgrit/tsconfig/node.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
  },
  "include": ["src/**/*.ts"],
}

You'll also need @types/node in your devDependencies:

npm install --save-dev @types/node

Library preset

For publishable npm libraries — sets rootDir/outDir and enables declaration emit:

{
  "extends": "@forgrit/tsconfig/library.json",
  // include is set to ["src/**/*.ts"]; override if needed
}

CommonJS library preset (new in v0.2.0)

For publishable npm libraries that need to ship CommonJS + ES2020 output (legacy Node.js compatibility, or consumers that haven't migrated to ESM yet):

{
  "extends": "@forgrit/tsconfig/commonjs-library.json",
  "compilerOptions": {
    // Optional per-package relaxations if the codebase predates strict defaults:
    // "noUncheckedIndexedAccess": false,
    // "isolatedModules": false,
  },
  "include": ["./**/*.ts"],
  "exclude": ["node_modules", "dist", "**/*.spec.ts", "**/*.test.ts"],
}

Inherits all of base.json's strictness + interop + decl emit, then overrides for CJS publish: target: ES2020, module: commonjs, moduleResolution: node, lib: [ES2020]. Also sets rootDir: ./, outDir: ./dist, composite: false, noEmit: false — matching the convention used by @forgrit/design-engine, @forgrit/design-intelligence, and @forgrit/contracts on npm.

What's enabled (base preset)

• Target: ES2022 + ES2022 lib
• Module: NodeNext + NodeNext moduleResolution (the modern Node.js + Bundler defaults)
• Strict: strict: true + noUncheckedIndexedAccess: true (you'll thank yourself later)
• Interop: esModuleInterop: true + forceConsistentCasingInFileNames: true
• Performance: skipLibCheck: true + isolatedModules: true + incremental: true
• Emit: declaration: true + declarationMap: true + sourceMap: true
• JSON: resolveJsonModule: true
• Excludes: node_modules, dist, .next, coverage

Why these defaults

• NodeNext matches Node's actual module resolution (vs the bundler-flavored alternatives), eliminating "works in Vite, breaks in Node" bugs.
• noUncheckedIndexedAccess catches the array[i] bug class (returns T when it should return T | undefined).
• declaration + declarationMap are non-negotiable for any code consumed downstream; declarationMap makes "go to definition" jump to your .ts source instead of .d.ts.
• isolatedModules + incremental keep both tsc and most bundlers (esbuild, swc, vite) happy.

License

MIT — see LICENSE.

Links

• npm: https://www.npmjs.com/package/@forgrit/tsconfig
• Source: https://github.com/forgrit-ai/forgrit/tree/main/tooling/tsconfig
• Issues: https://github.com/forgrit-ai/forgrit/issues
• ForGrit: https://forgrit.ai

Sibling packages (use these together)

• @forgrit/contracts — cross-domain Zod schemas + TypeScript types
• @forgrit/blueprint — app-spec format + blueprint helpers
• @forgrit/llm-cost — credit ledger primitives + 7 LLM cost design rules
• @forgrit/design-engine — recipe + theme combinatorial design engine
• @forgrit/design-intelligence — embedding + RAG + hybrid scoring