Skip to main content
The @zayne-labs/tsconfig package provides proper TypeScript configuration presets for most project types. Choose the right config based on your build tool and runtime environment.

​
Features

Multiple Presets

Configs for apps, libraries, and monorepos

Environment Support

Separate configs for DOM and non-DOM environments

Build Tool Variants

TSC and bundler-specific configurations

Framework Configs

Special presets for Next.js and more

​
Installation

pnpm add -D @zayne-labs/tsconfig

​
Usage

  1. Choose which tsconfig.json you need from the list below
  2. Add it to your tsconfig.json:
tsconfig.json
{
  "extends": "@zayne-labs/tsconfig/bundler/dom/app"
}

​
List of TSConfigs

The key question: Are you using tsc to turn your .ts files into .js files?
If you’re using TypeScript’s tsc compiler to emit JavaScript files:

​
DOM Environment

For code that runs in the browser:
{
  // For an app
  "extends": "@zayne-labs/tsconfig/tsc/dom/app",
  
  // For a library
  "extends": "@zayne-labs/tsconfig/tsc/dom/library",
  
  // For a library in a monorepo
  "extends": "@zayne-labs/tsconfig/tsc/dom/library-monorepo"
}

​
Non-DOM Environment

For code that runs in Node.js or other non-browser environments:
{
  // For an app
  "extends": "@zayne-labs/tsconfig/tsc/no-dom/app",
  
  // For a library
  "extends": "@zayne-labs/tsconfig/tsc/no-dom/library",
  
  // For a library in a monorepo
  "extends": "@zayne-labs/tsconfig/tsc/no-dom/library-monorepo"
}

​
Framework-Specific Configs

​
Next.js

For Next.js applications:
tsconfig.json
{
  "extends": "@zayne-labs/tsconfig/bundler/dom/next"
}
More framework-specific configurations will be added in future releases based on demand.

​
Config Types Explained

​
App vs Library vs Library-Monorepo

Use for applications that are deployed and run, not published as packages.
  • Includes all necessary DOM types
  • Optimized for bundler output
  • Suitable for web apps, CLIs, servers
Use for standalone libraries published to npm or other registries.
  • Configured for package distribution
  • Proper declaration file generation
  • Module resolution for consumers
Use for libraries within a monorepo that are consumed by other packages in the same repo.
  • Optimized for workspace references
  • Faster builds with project references
  • Shared type checking across packages

​
DOM vs Non-DOM

Use when your code runs in a browser environment:
  • Includes DOM type definitions
  • document, window, HTMLElement, etc.
  • Web APIs like fetch, localStorage
Examples:
  • React applications
  • Vue applications
  • Browser extensions
  • Client-side libraries

​
TSC vs Bundler

Use when TypeScript’s tsc compiler is your build tool:
  • module: "ESNext" or "CommonJS"
  • Proper module resolution
  • Declaration file generation
When to use:
  • Publishing libraries without a bundler
  • Node.js projects using tsc directly
  • When you need full TypeScript emit control

​
Customizing Configs

Extend the base config and override specific options:
tsconfig.json
{
  "extends": "@zayne-labs/tsconfig/bundler/dom/app",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"]
    },
    "target": "ES2022"
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

​
Common Customizations

​
Path Aliases

tsconfig.json
{
  "extends": "@zayne-labs/tsconfig/bundler/dom/app",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@lib/*": ["./src/lib/*"],
      "@components/*": ["./src/components/*"]
    }
  }
}

​
Strict Type-Checking

tsconfig.json
{
  "extends": "@zayne-labs/tsconfig/bundler/dom/app",
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true
  }
}

​
Monorepo with Project References

tsconfig.json
{
  "extends": "@zayne-labs/tsconfig/bundler/dom/library-monorepo",
  "compilerOptions": {
    "composite": true,
    "declarationMap": true
  },
  "references": [
    { "path": "./packages/shared" },
    { "path": "./packages/utils" }
  ]
}

​
Examples by Project Type

​
React Application (Vite)

tsconfig.json
{
  "extends": "@zayne-labs/tsconfig/bundler/dom/app",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    },
    "jsx": "react-jsx"
  },
  "include": ["src"]
}

​
Next.js Application

tsconfig.json
{
  "extends": "@zayne-labs/tsconfig/bundler/dom/next",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

​
Node.js CLI Tool

tsconfig.json
{
  "extends": "@zayne-labs/tsconfig/tsc/no-dom/app",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}

​
Published Library (with Bundler)

tsconfig.json
{
  "extends": "@zayne-labs/tsconfig/bundler/dom/library",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "declarationMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["**/*.test.ts", "**/*.spec.ts"]
}

​
Base Configuration

All presets extend a base configuration with sensible defaults. To use only the base:
tsconfig.json
{
  "extends": "@zayne-labs/tsconfig/base"
}
The base config is minimal and requires additional configuration. Use specific presets instead for production projects.

​
Decision Tree

Use this flowchart to choose the right config:

​
FAQ

Use @zayne-labs/tsconfig/bundler/dom/app since Vite is a bundler and React runs in the DOM.
library-monorepo is optimized for packages within a monorepo using project references, while library is for standalone packages.
Yes! Create separate tsconfig.json files for different parts of your project (e.g., tsconfig.node.json for build scripts).
Yes, this package only provides configuration presets. Install TypeScript as a dev dependency: pnpm add -D typescript

​
Credits

Inspired by Matt Pocock’s TSConfig Cheat Sheet from Total TypeScript.

​
License

MIT © Ryan Zayne

Build docs developers (and LLMs) love

Get started for freeTalk to us