This document details the production compilation, optimization, and artifact generation process for both the NestJS framework packages and user applications. It covers TypeScript compilation strategies, build scripts, output artifacts, and the complete build pipeline from source to deployable JavaScript.
For information about development build tools and hot module replacement, see Webpack Integration. For deployment strategies and running built applications, see Deployment and Production.
The NestJS build process encompasses two distinct but related workflows:
This document covers both workflows, their configuration, optimization strategies, and the resulting build artifacts.
Sources: package.json16-51 sample/06-mongoose/package.json6-19
The NestJS framework itself uses TypeScript's project references (-b flag) to build multiple interdependent packages efficiently.
| Script | Command | Purpose |
|---|---|---|
build | tsc -b -v packages | Standard incremental build of all packages |
build:dev | tsc -b -v packages --watch | Watch mode for development |
build:prod | tsc -b -v packages | Production build with pre-clean step |
clean | tsc -b --clean packages | Remove all build artifacts |
Sources: package.json17-23
The -b (build) flag enables TypeScript's build mode, which:
tsconfig.json.tsbuildinfo files.d.ts) for type checkingSources: package.json17-23
Sources: package.json20-21 package.json18 package.json24-25
Before publishing to npm, additional steps prepare the packages:
Sources: package.json44-50
Individual NestJS applications use the NestJS CLI for building, which provides a streamlined developer experience.
Sources: sample/06-mongoose/package.json7-13
The nest build command compiles TypeScript code using either:
tsc (TypeScript Compiler)nest-cli.json)| Build Option | Description |
|---|---|
nest build | Standard production build |
nest build --watch | Watch mode for development |
nest build --webpack | Force webpack compilation |
nest build --tsc | Force TypeScript compiler |
After running nest build, the output directory structure mirrors the source structure:
dist/
├── main.js # Application entry point
├── main.js.map # Source map
├── app.module.js # Root module
├── app.controller.js # Controllers
├── app.service.js # Services
└── [other-modules]/ # Feature modules
├── *.js
└── *.js.map
Sources: sample/06-mongoose/package.json13
| Script | Command | Use Case |
|---|---|---|
build | tsc -b -v packages | Standard development build |
build:dev | tsc -b -v packages --watch | Continuous compilation during development |
build:prod | tsc -b -v packages | Clean build for production/release |
clean | tsc -b --clean packages | Remove all compiled artifacts |
postbuild | npm run move:node_modules | Post-compilation setup |
prerelease | gulp copy-misc | Prepare packages for npm publish |
Sources: package.json17-44
| Script | Command | Use Case |
|---|---|---|
prebuild | rimraf dist | Clean previous build |
build | nest build | Compile application for production |
start:prod | node dist/main | Run compiled production build |
Sources: sample/06-mongoose/package.json7-13 sample/22-graphql-prisma/package.json7-14
The production build uses strict TypeScript settings to ensure type safety:
Key compilation settings:
.d.ts files for TypeScript consumersSources: package.json174-176
For each package in the monorepo, the build produces:
packages/[package-name]/
├── src/ # Source TypeScript files
│ └── *.ts
├── dist/ # Build output
│ ├── *.js # Compiled JavaScript
│ ├── *.d.ts # Type declarations
│ ├── *.js.map # Source maps
│ └── *.d.ts.map # Declaration maps
├── tsconfig.json # Package-specific config
├── package.json # Package metadata
└── .tsbuildinfo # Incremental build cache
TypeScript's incremental compilation uses .tsbuildinfo files to track:
This enables faster rebuilds by only recompiling changed files and their dependents.
Sources: package.json17-23
Development builds (npm run build):
.tsbuildinfo cacheProduction builds (npm run build:prod):
prebuild:prod to clean firstSources: package.json20-23
The framework build leverages TypeScript project references for parallel compilation:
TypeScript automatically determines which packages can be built in parallel based on their dependency relationships, maximizing CPU utilization.
Sources: package.json17
NPM's lifecycle scripts automatically execute:
prebuild:prod runs before build:prodpostbuild runs after buildSources: package.json18-21
The publish process ensures:
build:prod)Sources: package.json44-50
| Script | Tag | Use Case |
|---|---|---|
publish | latest | Stable release |
publish:beta | beta | Beta testing |
publish:next | next | Preview of upcoming features |
publish:rc | rc | Release candidate |
publish:test | test | Testing publish process |
Sources: package.json45-50
Some applications have additional build steps for generating types:
Sources: sample/22-graphql-prisma/package.json9
Applications may include additional configuration:
| File | Purpose |
|---|---|
nest-cli.json | NestJS CLI build settings |
tsconfig.json | TypeScript compiler options |
tsconfig.build.json | Production-specific TypeScript config |
webpack.config.js | Webpack build configuration (if used) |
| Issue | Cause | Solution |
|---|---|---|
| Stale build artifacts | Incremental build cached outdated files | Run npm run clean then rebuild |
| Type errors in production | Different tsconfig.json settings | Check tsconfig.build.json excludes test files |
| Missing dependencies | Package not in dependencies (only devDependencies) | Move to dependencies for runtime use |
| Import errors | Incorrect module resolution | Verify paths in tsconfig.json |
| Build too slow | No incremental compilation | Ensure .tsbuildinfo files are preserved |
After building, verify the output:
Sources: package.json20-23 sample/06-mongoose/package.json7-13
The NestJS build process provides two complementary workflows:
tsc -b) for efficient monorepo compilation with parallelization and incremental buildsnest build) for streamlined application compilation with sensible defaultsBoth workflows produce optimized JavaScript output with source maps and type declarations, ready for production deployment. The build system prioritizes developer experience during development (incremental, watch mode) while ensuring clean, verified builds for production releases.
Sources: package.json16-51 sample/06-mongoose/package.json6-19 sample/22-graphql-prisma/package.json7-14
Refresh this wiki