typescript
/

TypeScript Config – tsconfig.json Mastery

Last Sync: Today

On this page

16
0%
5 min read
Remaining
5 minleft

Click any section to jump — progress syncs automatically

typescript

TypeScript Config – tsconfig.json Mastery

What is tsconfig.json?

tsconfig.json is the configuration file for TypeScript projects. It defines compiler options, file inclusion/exclusion rules, and project settings. Without it, TypeScript uses default settings.

Basic tsconfig.json

JSONRead-only
1
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

Complete Compiler Options Reference

CategoryOptionDescriptionRecommended
LanguagetargetJS version outputES2020+
LanguagelibRuntime librariesES2020, DOM
LanguagejsxJSX supportreact-jsx
ModulesmoduleModule systemESNext/CommonJS
ModulesmoduleResolutionModule resolutionbundler/node10
ModulesresolveJsonModuleImport JSONtrue
OutputoutDirOutput directory./dist
OutputrootDirSource root./src
OutputdeclarationGenerate .d.tstrue (libraries)
OutputsourceMapSource mapstrue
StrictstrictAll strict flagstrue
StrictnoImplicitAnyDisallow anytrue
StrictstrictNullChecksNull safetytrue
InteropesModuleInteropES interoptrue
InteropallowSyntheticDefaultImportsDefault importstrue
PerformanceskipLibCheckSkip .d.ts checktrue
PerformanceincrementalIncremental buildstrue

Preset Configurations by Project Type

Node.js Backend

JSONRead-only
1
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "sourceMap": true,
    "removeComments": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

React Frontend

JSONRead-only
1
{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "noEmit": true,
    "allowJs": true,
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "resolveJsonModule": true
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
}

Library (npm Package)

JSONRead-only
1
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "lib": ["ES2020"],
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
}

Path Mapping

JSONRead-only
1
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"],
      "@types/*": ["src/types/*"]
    }
  }
}

Project References (Monorepo)

JSONRead-only
1
// tsconfig.base.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

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

// apps/web/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "references": [
    { "path": "../../packages/core" }
  ],
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

Type Checking Options

JSONRead-only
1
{
  "compilerOptions": {
    // Strict family
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictBindCallApply": true,
    "strictPropertyInitialization": true,
    "noImplicitThis": true,
    "useUnknownInCatchVariables": true,
    
    // Linter-like checks
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "noPropertyAccessFromIndexSignature": true
  }
}

Extended Configurations

JSONRead-only
1
// tsconfig.base.json - Shared settings
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2020",
    "module": "ESNext"
  }
}

// tsconfig.dev.json - Development overrides
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true
  }
}

// tsconfig.prod.json - Production overrides
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "removeComments": true,
    "sourceMap": false
  }
}

CLI Flags vs tsconfig.json

Use Casetsconfig.jsonCLI Flag
Project-wide settings✅ Best❌ Cumbersome
One-off builds❌ Overkill✅ Quick
Team consistency✅ Required❌ Not shared
CI/CD pipelines✅ Best⚠️ Possible
Watch mode✅ tsc --watch✅ tsc --watch

Debugging Configuration

JSONRead-only
1
{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true,
    "sourceRoot": "/",
    "mapRoot": "/",
    "outDir": "./dist",
    "removeComments": false
  }
}

// VS Code launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug TypeScript",
      "runtimeArgs": ["-r", "ts-node/register"],
      "args": ["${workspaceFolder}/src/index.ts"],
      "sourceMaps": true
    }
  ]
}

Common Mistakes

  • Forgetting to set rootDir – Causes unexpected output structure
  • Using outDir instead of rootDir – Misunderstood paths
  • Not using strict mode – Missing type safety benefits
  • Including node_modules – Slow compilation
  • Missing declaration files for libraries – No .d.ts output
  • Inconsistent module resolution – Import errors

Best Practices

  • Always enable strict mode – Catch more errors
  • Use incremental builds – Faster compilation
  • Extend base configs – DRY configuration
  • Set correct target – Based on your environment
  • Use project references – For monorepos
  • Commit tsconfig.json – Share with team
  • Validate config – Use tsc --showConfig

Conclusion

tsconfig.json is the heart of every TypeScript project. Understanding compiler options enables you to optimize builds, enforce coding standards, and configure TypeScript for any environment. Start with strict mode and customize based on your project needs.

Try it yourself

// This code demonstrates tsconfig.json settings

// With strictNullChecks: true, this would error if not handled
function getValue(value: string | null): string {
  // Without strictNullChecks, this would be allowed
  // With strictNullChecks, we need proper handling
  return value ?? 'default value';
}

// With noUnusedLocals: true, this would cause a warning
// const unusedVariable = 'this would trigger a warning';

// With noImplicitAny: true, this would error
// function processData(data) {  // 'data' would have implicit any
//   return data.value;
// }

// Proper typing
interface Data {
  value: string;
}

function processData(data: Data): string {
  return data.value;
}

// With resolveJsonModule: true
import packageJson from './package.json' assert { type: 'json' };
console.log('TypeScript version:', packageJson.devDependencies?.typescript);

// Check your tsconfig.json settings!
console.log('Configuration affects how this code is checked');

Test Your Knowledge

Q1
of 4

Which option enables all strict type checking flags?

A
noImplicitAny
B
strict
C
strictNullChecks
D
forceConsistentCasingInFileNames
Q2
of 4

What does 'outDir' specify?

A
Source directory
B
Output directory
C
Type directory
D
Config directory
Q3
of 4

Which flag generates declaration files?

A
emitDeclaration
B
declaration
C
dts
D
types
Q4
of 4

How to extend another tsconfig.json?

A
extends
B
inherit
C
base
D
parent

Frequently Asked Questions

What is tsconfig.json?

Configuration file that specifies compiler options and files to include in a TypeScript project.

Strict mode vs noImplicitAny?

Strict enables all strict family flags; noImplicitAny only prevents implicit any.

What are project references?

Feature that allows TypeScript projects to depend on each other for better build performance.

How to see effective config?

Run tsc --showConfig to see the resolved configuration.

Previous

ts fetch

Next

ts build

Related Content

Need help?

Explore our comprehensive docs or start a chat with our tech experts.