When modern full-stack web applications start out, organizing backend Express endpoints and frontend React views inside a single repository is undeniably convenient. A developer writes an API route in src/routes/, imports a type in src/views/, and relies on a unified tsconfig.json to build the entire system. However, as an enterprise application scales to support dozens or hundreds of tenant domains, thousands of UI components, and rich visual libraries, this monolithic compilation strategy hits an unforgiving wall: catastrophic compiler memory consumption and agonizingly slow build times.

The Monolithic tsconfig.json Trap

In a standard TypeScript project, the compiler configuration typically declares "include": ["src"]. To verify correctness, the TypeScript compiler (tsc) parses every reachable source file into an in-memory Abstract Syntax Tree (AST), generates comprehensive symbol tables, and evaluates every type declaration. In a multi-tenant platform like multiDomainCMS—which hosts 142 distinct domain views alongside high-throughput Express microservices—the monolithic compiler is forced to load:

• 320+ Backend Source Files: Express routes, MongoDB Mongoose models, MySQL pools, authentication middleware, and background workers.
• 2,500+ Frontend React Views: Domain-specific JSX layouts, client dashboards, SVG iconography, and interactive state hooks.
• 2,000+ Type Declaration Files: Heavy external libraries including React 19, Three.js (over 530 declaration files), Radix UI primitives, Lucide icons, and Framer Motion.

Under this monolithic paradigm, a backend engineer tweaking a single SQL query or Express route causes tsc to re-evaluate the entire multi-tenant universe. The compiler must parse 700,000+ lines of code across 4,800+ files simply to ensure a backend controller returns a JSON response.

V8 Garbage Collection Thrashing & The 2GB Memory Ceiling

The consequence of whole-program AST construction is immense memory pressure. Node.js processes run on Google's V8 engine, which historically defaults to an Old Space heap limit of roughly 2.0 GB to 2.5 GB on 64-bit operating systems. When the compiler's live retained objects cross 2.0 GB, V8 begins thrashing—running continuous major Garbage Collection (GC) sweeps that reclaim less than 5% of memory per cycle.

Eventually, the compiler crashes with the familiar runtime failure:

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

While increasing Node's memory ceiling via NODE_OPTIONS="--max-old-space-size=4096" treats the symptom, it does not cure the underlying architectural disease. Why should a backend microservice require 4 gigabytes of RAM to verify a database query?

Enter TypeScript Project References (composite: true)

TypeScript 3.0 introduced Project References specifically to solve monolithic build decay. Rather than treating a monorepo as a single undifferentiated ocean of source code, Project References allow engineering teams to define explicit, independent compilation boundaries.

In our decoupled architecture, we split the monolithic configuration into three distinct, composable layers:

1. The Shared Foundation (tsconfig.base.json)

The base configuration establishes universal compiler flags, strict type-checking invariants, module resolution, and path aliases without including any source files:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "paths": {
      "@/*": ["./src/*"],
      "@views/*": ["./src/views/*"]
    }
  }
}

2. The Backend Server Boundary (tsconfig.server.json)

The backend project strictly encapsulates server-side execution. Notice the critical architectural isolation: it includes only backend folders, explicitly excludes src/views, and loads only Node, Express, and database type definitions:

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "composite": true,
    "rootDir": "./src",
    "outDir": "./dist",
    "types": ["node", "express", "mongodb"]
  },
  "include": [
    "src/index.ts",
    "src/controllers/**/*",
    "src/routes/**/*",
    "src/services/**/*",
    "src/config/**/*",
    "src/types/**/*"
  ],
  "exclude": [
    "src/views",
    "src/**/__tests__"
  ]
}

Because React, Three.js, and browser DOM definitions are completely excluded from the backend compiler's type roots, tsc evaluates only ~320 files instead of 4,825. Memory consumption plummets to under 80 MB, and compile time drops from seconds to an instantaneous 110 milliseconds.

3. The Frontend View Boundary (tsconfig.views.json)

The frontend view project handles the 142 tenant domains and their JSX component trees. It enables React JSX compilation, targets DOM and React types, and runs with "noEmit": true:

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "composite": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "types": ["node", "react", "react-dom"]
  },
  "include": [
    "src/views/**/*",
    "src/types/**/*"
  ],
  "exclude": [
    "src/views/components",
    "src/**/__tests__"
  ]
}

4. Root Orchestration (tsconfig.json)

The root configuration orchestrates both projects using references. When running tsc -b (build mode), TypeScript analyzes the dependency graph, builds projects in topological order, and caches compilation metadata in incremental .tsbuildinfo files:

{
  "files": [],
  "references": [
    { "path": "./tsconfig.server.json" },
    { "path": "./tsconfig.views.json" }
  ]
}

How Server-Side Rendering (SSR) Survives Decoupling

A natural question from full-stack engineers is: If the backend compiler does not parse the view files, how can Express render React components on the server without failing type verification?

In our architecture, Express controllers utilize dynamic view dispatching. Controllers resolve the tenant domain and invoke React's server-side rendering API (renderToString):

import React from 'react';
import { renderToString } from 'react-dom/server';

export function renderDomainView(req: Request, res: Response, viewPath: string, props: any) {
  const Component = require(`../views/${req.tenantDomain}/${viewPath}`).default;
  const html = renderToString(React.createElement(Component, props));
  res.send(`<!DOCTYPE html>${html}`);
}

The backend server relies on a functional component contract: it requires only that the target module exports a renderable React function accepting properties. The server never needs to inspect internal CSS class lists, Lucide SVG paths, or Three.js WebGL canvas refs inside tenant views to guarantee API correctness.

Quantitative Performance Benchmarks

The impact of Project References on developer productivity and CI pipeline throughput is dramatic:

• Files Analyzed During Backend Build: Dropped from 4,825 to ~320 files (a 93.3% reduction).
• Lines of Code Processed: Dropped from 716,446 to ~64,000 lines (a 91.1% reduction).
• Compiler Memory Usage: Reduced from 515 MB+ to <80 MB (an 84% reduction).
• Build Latency: Backend compilation dropped from ~1,200ms to 120ms (a 10x speedup).
• Incremental Caching: Subsequent rebuilds complete in under 50 milliseconds via isolated .tsbuildinfo caches.

Conclusion

Monolithic TypeScript configurations are fine for small applications, but enterprise multi-tenant systems inevitably outgrow them. By implementing TypeScript Project References, engineering teams can cleanly decouple backend execution from frontend presentation, eliminate V8 garbage collection thrashing, and deliver lightning-fast compilation feedback without sacrificing type safety or server-side rendering fidelity.