# TypeScript Performance Optimization: Faster Builds, Better DX — Hunchbite

> How to configure TypeScript for fast builds and responsive IDE feedback — incremental compilation, tsconfig tuning, decoupling type checking from transpilation, and project references for monorepos.

Source: https://hunchbite.com/guides/typescript-dx-optimization

[Home](https://hunchbite.com/)/[Guides](https://hunchbite.com/guides)/[Technology Decisions](https://hunchbite.com/guides/topic/technology-decisions)/TypeScript Performance Optimization: Faster Builds, Better DX

[Technology Decisions](https://hunchbite.com/guides/topic/technology-decisions)

# TypeScript Performance Optimization: Faster Builds, Better DX

How to configure TypeScript for fast builds and responsive IDE feedback — incremental compilation, tsconfig tuning, decoupling type checking from transpilation, and project references for monorepos.

By HunchbiteMarch 30, 20269 min read

TypeScriptdeveloper experienceDX

TypeScript's type safety is worth the tradeoff — until the build takes 3 minutes and the IDE takes 5 seconds to show an autocomplete suggestion.

The performance problems are predictable and fixable. This guide covers the specific configurations that make TypeScript fast at scale: incremental compilation, tsconfig tuning, separating type checking from transpilation, and project references for monorepos.

## Why TypeScript gets slow

Three things cause TypeScript to slow down as codebases grow:

**1\. No incremental builds.** By default, `tsc` re-analyses every file from scratch. At 500+ files, this adds up.

**2\. Checking node\_modules type definitions.** Your dependencies ship `.d.ts` files. Checking them adds significant time, and you didn't write them — there's nothing actionable you can do with those errors.

**3\. Type checking coupled to the build.** When your bundler runs `tsc` as part of the build, every hot-reload waits for type checking to complete. These are different concerns and should run separately.

## tsconfig.json: the high-leverage settings

```
{
  "compilerOptions": {
    // Performance
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo",
    "skipLibCheck": true,
 
    // Correctness
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
 
    // Compatibility
    "moduleResolution": "bundler",
    "target": "ES2022",
    "lib": ["dom", "dom.iterable", "esnext"],
    "esModuleInterop": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

**`incremental: true`** — TypeScript saves a `.tsbuildinfo` file after each compilation. On subsequent builds, it reads this file and only rechecks files that have changed. First build is unchanged; subsequent builds are dramatically faster.

**`skipLibCheck: true`** — Skips type checking of `.d.ts` files in `node_modules`. This is almost always correct: you're not fixing library type errors, and checking them adds significant time for zero benefit.

**`noUncheckedIndexedAccess: true`** — Goes beyond `strict` mode. Array access (`arr[0]`) and object index access return `T | undefined` instead of `T`. This catches a class of runtime errors that `strict` misses.

## Decouple type checking from your build

This is the highest-leverage change for development speed. Most setups run type checking as part of the build, which means every file save blocks on the TypeScript compiler.

The correct approach:

**Your bundler handles transpilation only.** Tools like SWC and esbuild strip TypeScript types to produce JavaScript near-instantly — they don't check types at all. This is correct for development: you need runnable code, not verified code.

**Type checking runs separately.** Run `tsc --noEmit --watch` in a terminal alongside your dev server. Errors appear in that terminal. They don't block your build.

In a Next.js project:

```
# Terminal 1: dev server (fast, no type checking)
bun run dev
 
# Terminal 2: type checker (runs in background, reports errors)
bun run tsc --noEmit --watch
```

Or as a package.json script:

```
{
  "scripts": {
    "type-check": "tsc --noEmit",
    "type-check:watch": "tsc --noEmit --watch"
  }
}
```

In CI, run `type-check` as a separate job — in parallel with lint and tests, not blocking the build.

## VS Code settings that matter for large codebases

Add `.vscode/settings.json` to your project so these apply to everyone on the team:

```
{
  "typescript.preferences.includePackageJsonAutoImports": "off",
  "typescript.suggest.autoImports": true,
  "typescript.updateImportsOnFileMove.enabled": "always",
  "editor.codeActionsOnSave": {
    "source.organizeImports": "explicit"
  }
}
```

**`includePackageJsonAutoImports: "off"`** — Without this, VS Code scans every `package.json` in `node_modules` when generating auto-import suggestions. In a monorepo, this causes significant autocomplete lag. Turning it off has no practical downside — it just stops suggesting obscure internal package paths.

## Project references in monorepos

In a monorepo with multiple TypeScript packages, changing one package triggers a full recheck of all packages by default. Project references fix this. This pays off most in large multi-app repos — for example a [headless commerce setup](https://hunchbite.com/guides/medusa-vs-shopify-vs-saleor) with a storefront, an admin, and several shared packages.

Each package gets a `tsconfig.json` that declares its dependencies:

```
// packages/ui/tsconfig.json
{
  "extends": "@repo/typescript-config/base.json",
  "compilerOptions": {
    "composite": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "references": [
    { "path": "../utils" }
  ]
}
```

The root `tsconfig.json` references all packages:

```
// tsconfig.json (root)
{
  "files": [],
  "references": [
    { "path": "./packages/utils" },
    { "path": "./packages/ui" },
    { "path": "./apps/web" }
  ]
}
```

Build with `tsc --build` (or `tsc -b`) instead of `tsc`. TypeScript now understands the dependency graph and only rebuilds packages affected by your change.

`composite: true` is required on referenced packages — it tells TypeScript that this package will be referenced by others, and enables the incremental outputs that make this work.

## Measuring the improvement

Before making changes, baseline your current build time:

```
time tsc --noEmit
```

After enabling incremental builds, run it twice — the second run shows the cached improvement:

```
time tsc --noEmit  # first run (cold)
time tsc --noEmit  # second run (should be 60-80% faster)
```

For a 500-file codebase, expect cold build around 15–30 seconds, incremental build 3–8 seconds. At 2,000 files, incremental builds stay fast while cold builds scale linearly.

## The common mistakes

**Running `tsc` in your webpack/vite config.** `ts-loader` with `transpileOnly: false` runs full type checking on every file save. Switch to `transpileOnly: true` or replace with `swc-loader` entirely.

**Not committing `.tsbuildinfo`.** If CI deletes `node_modules` and `.tsbuildinfo` between runs, incremental builds don't help in CI. Cache `.tsbuildinfo` along with `node_modules`.

**Circular dependencies.** TypeScript handles circular imports differently from bundlers and they silently degrade type inference quality. Use `madge --circular .` to find them.

---

A slow TypeScript setup is usually a configuration problem, not a scale problem. These changes — incremental builds, skipLibCheck, decoupled type checking, and project references — are what we implement as part of every DX engagement.

If your team is spending meaningful time waiting on TypeScript, that's engineering time that should be building product.

**[→ Developer Experience Consultancy](https://hunchbite.com/services/developer-experience-consultancy)**

Call [+91 90358 61690](tel:+919035861690) · [Book a free call](https://cal.com/hunchbite/discovery) · [Contact form](https://hunchbite.com/contact)

Ask an AI assistant about this guide: [ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fhunchbite.com%2Fguides%2Ftypescript-dx-optimization%20and%20help%20me%20apply%20it%20to%20my%20situation.%20Answer%20my%20questions%20about%20it.&hints=search) · [Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fhunchbite.com%2Fguides%2Ftypescript-dx-optimization%20and%20help%20me%20apply%20it%20to%20my%20situation.%20Answer%20my%20questions%20about%20it.) · [Perplexity](https://www.perplexity.ai/search?q=Read%20https%3A%2F%2Fhunchbite.com%2Fguides%2Ftypescript-dx-optimization%20and%20help%20me%20apply%20it%20to%20my%20situation.%20Answer%20my%20questions%20about%20it.)

On this page

* [Why TypeScript gets slow](#why-typescript-gets-slow)
* [tsconfig.json: the high-leverage settings](#tsconfigjson-the-high-leverage-settings)
* [Decouple type checking from your build](#decouple-type-checking-from-your-build)
* [VS Code settings that matter for large codebases](#vs-code-settings-that-matter-for-large-codebases)
* [Project references in monorepos](#project-references-in-monorepos)
* [Measuring the improvement](#measuring-the-improvement)
* [The common mistakes](#the-common-mistakes)

Ask AI about this guide

* [Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fhunchbite.com%2Fguides%2Ftypescript-dx-optimization%20and%20help%20me%20apply%20it%20to%20my%20situation.%20Answer%20my%20questions%20about%20it.&hints=search)
* [Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fhunchbite.com%2Fguides%2Ftypescript-dx-optimization%20and%20help%20me%20apply%20it%20to%20my%20situation.%20Answer%20my%20questions%20about%20it.)
* [Open in Perplexity](https://www.perplexity.ai/search?q=Read%20https%3A%2F%2Fhunchbite.com%2Fguides%2Ftypescript-dx-optimization%20and%20help%20me%20apply%20it%20to%20my%20situation.%20Answer%20my%20questions%20about%20it.)

FAQ

Why does TypeScript slow down as a codebase grows?

TypeScript's type checker does more work as the codebase grows — more files to analyse, more types to infer, more cross-file relationships to track. Without incremental compilation, it re-checks everything from scratch on each build. The fix is a combination of incremental builds (cache what hasn't changed), skipLibCheck (skip node\_modules type files), and decoupling type checking from transpilation so they don't block each other.

What's the difference between transpilation and type checking?

Transpilation strips TypeScript syntax to produce runnable JavaScript — tools like SWC and esbuild do this near-instantly because they don't validate types. Type checking verifies correctness against your type definitions — this is what \`tsc\` does and what's slow at scale. Separating them means your code runs immediately while type checking happens in the background, which is the right tradeoff for development speed.

Should I use project references in a monorepo?

Yes, if you have multiple packages with clear dependency relationships. Project references tell TypeScript exactly which packages depend on which, so a change in one package only triggers a recheck of that package and its dependents — not the entire monorepo. The overhead to set up is low; the build time savings at 20+ packages are significant.

Weighing a technical decision?

## Get a second opinion before you commit.

Stack choices, architecture trade-offs, build-vs-buy — a 30-minute call with senior engineers can save you months. No sales pitch, just a straight answer.

[Book a Free Call](https://cal.com/hunchbite/discovery)[Have Us Build It](https://hunchbite.com/custom-software-development-company)

Trusted by VMAC Industries, TKD Logistics, Astitva Jewellery & more. [See our recent work →](https://hunchbite.com/case-studies)

Fixed-price, no hourly billing · No obligation · We tell you upfront if we're not a fit

Continue Reading

[Technology DecisionsMulti-Tenant SaaS Architecture: Row-Level Security vs. Schema-Per-TenantThe two main approaches to multi-tenancy in SaaS products — row-level security and schema-per-tenant — with an honest comparison of when each makes sense, performance characteristics, migration costs, and the decision framework senior teams actually use.12 min read](https://hunchbite.com/guides/multi-tenant-saas-architecture)

[Technology DecisionsStripe Billing for SaaS: Subscriptions, Usage-Based Pricing, and the Edge Cases That Break ThingsA practical guide to implementing Stripe billing in a SaaS product — covering subscription models, metered usage, free trials, dunning, proration, and the specific edge cases that break billing implementations and cause revenue leakage.11 min read](https://hunchbite.com/guides/stripe-billing-saas)

[All Guides](https://hunchbite.com/guides)
