TypeScript Configuration

Relevant source files

Purpose and Scope

This document details the TypeScript configuration setup used throughout the NestJS monorepo. It covers the TypeScript compiler version, project references for incremental builds using tsc -b, runtime execution with ts-node, and path mapping configuration. For information about the overall build system and development workflow, see Build System and Development Tools. For testing infrastructure that relies on TypeScript compilation, see Testing Infrastructure.

TypeScript Compiler Version

The NestJS monorepo uses TypeScript 5.9.3 as specified in package.json170 This version is pinned across the monorepo to ensure consistent type checking and compilation behavior across all core packages and integration tests.

Node.js Version Requirement: The repository requires Node.js >= 20 as specified in package.json174-176

Sources: package.json170 package.json174-176

TypeScript Build System Architecture

The monorepo architecture relies on a "Project References" approach, where the root tsconfig.json coordinates the compilation of individual packages.

Diagram: TypeScript compilation architecture in the NestJS monorepo

Sources: package.json17-23 package.json140 packages/common/tsconfig.json1-5 packages/core/tsconfig.json1-5

Project References and Incremental Builds

The monorepo uses TypeScript's project references feature with the -b (build mode) flag for efficient incremental compilation across the core packages located in the packages/ directory.

Build Commands

Command	Script	Purpose
`npm run build`	`tsc -b -v packages`	Full build of all packages in dependency order package.json17
`npm run build:dev`	`tsc -b -v packages --watch`	Watch mode for development package.json19
`npm run clean`	`tsc -b --clean packages`	Removes build artifacts and `.tsbuildinfo` package.json23
`npm run build:prod`	`tsc -b -v packages`	Production build used during release package.json21

The -b flag enables:

Dependency ordering: Automatically builds packages like @nestjs/common before @nestjs/core if the latter depends on the former.
Fast rebuilds: Uses .tsbuildinfo files to track what needs recompilation.
Verbose output: The -v flag provides detailed logs of the compilation progress.

Sources: package.json17-23 lerna.json2

Dependency Mapping

The relationship between packages is defined in their respective package.json files and reflected in the TypeScript project references.

Diagram: Package dependency hierarchy for TypeScript compilation

Sources: packages/core/package.json33-35 packages/platform-express/package.json31-34 packages/microservices/package.json28-32 packages/testing/package.json23-27

Runtime Execution and Testing

NestJS uses several tools to handle TypeScript at runtime or during the testing phase without requiring a full manual compilation step.

ts-node for Mocha Tests

The monorepo uses ts-node (version 10.9.2) to execute unit and integration tests directly. This is configured via the --loader flag in the test scripts.

Unit Tests: node --loader ts-node/esm ./node_modules/mocha/bin/mocha.js packages/**/*.spec.ts package.json30
Integration Tests: node --loader ts-node/esm ./node_modules/mocha/bin/mocha.js ... "integration/*/*.spec.ts" package.json34

Path Mapping with tsconfig-paths

To resolve module aliases (e.g., importing from @nestjs/core within an integration test), the framework utilizes tsconfig-paths (version 4.2.0). This allows the runtime to map package names to their source locations in the monorepo.

Sources: package.json167-168 package.json30-34

Gulp and Build Automation

While tsc -b handles the primary TypeScript compilation, Gulp is used for supplementary tasks such as moving assets and specific package transformations.

gulp-typescript: Used for specific build tasks where tsc alone is insufficient package.json140
Source Maps: Enabled via gulp-sourcemaps to ensure that stack traces in development point back to the original .ts files package.json139

Sources: package.json136-141 gulpfile.js1-10