Recipes & Tooling

Source: NestJS: SWC, NestJS: CLI usage - nest build

A build with both options on looks like this:

dist then held app.module.js, app.module.js.map, main.js, their .d.ts files and a tsconfig.build.tsbuildinfo. The declaration for a small module is what tsc would have written:

Source: NestJS: CLI workspaces - Global compiler options, NestJS: SWC - Type checking

Declaration files matter when the project is a library that other packages import (see Project Structure & Workspaces); an application does not need them, so leave emitDeclarations off. Type checking matters always: without it a type error compiles and ships (the demonstration is in the CLI page). In watch mode the check runs asynchronously, so the process restarts quickly and the errors appear next to it. A CI job should build with typeCheck on, or run tsc --noEmit as a separate step.

On speed: the documentation claims SWC is about 20 times faster than the TypeScript compiler on its recipe page, and about 10 times on the CLI overview page. On a six-file project the difference is not visible: nest build -b tsc takes about 0.72 s and nest build -b swc --no-type-check about 0.76 s wall time, although SWC itself reports some 22 ms for the compile, because starting the CLI dominates a build that small. The factor depends on the project size and on whether type checking is on (it is the slow part), so measure your own project before promising a number.

Without a .swcrc the builder emits the module format that tsc would: ES modules when package.json has "type": "module" (the default of new projects) and CommonJS otherwise. A .swcrc that sets module overrides that choice, which is a common way to break an ESM project. This .swcrc in the root of an ESM project makes nest build succeed and the application crash at start-up:

The fix is to leave module out of .swcrc in ESM projects. In a CommonJS project, the setting "module": { "type": "commonjs" } is what Jest needs (below).

To keep the SWC configuration somewhere other than the root, point the builder at it:

The build succeeded, wrote no .js.map files (the file asked for none), and dist/main.js was still an ES module. The settings in the file are merged over the builder’s Nest defaults rather than replacing them: a second run with an infrastructure/.swcrc that contained only { "sourceMaps": false } still emitted the decorator and metadata helpers (_ts_decorate, _ts_metadata) and the application started and served requests. That is different from Jest with @swc/jest (below), which does not use the builder’s defaults and needs the decorator settings spelled out in its own .swcrc.

Source: NestJS: SWC - Getting started, NestJS: SWC - SWC configuration

Nest resolves constructor parameters from the metadata that emitDecoratorMetadata writes, and SWC writes it too (decoratorMetadata in .swcrc, preconfigured by the builder). The metadata of a decorated property refers to the property’s class by name at class-definition time. With two entities that import each other, that reference is read while the other module is still being initialised, and in ES modules the result is a ReferenceError. The recipe calls this out for SWC, but it is not specific to it: the same pair compiled with tsc in the ESM project failed identically.

The fix is the wrapper type from the recipe: Relation<T> from TypeORM, which is just T to the type checker but a type that has no runtime value, so the metadata falls back to Object. One detail the recipe omits matters with the current templates: because isolatedModules and emitDecoratorMetadata are both on, TypeScript 6 rejects a plain import of Relation in a decorated signature with error TS1272, and it must be imported with import type:

With both entities changed, nest build reports Found 0 issues, and a DataSource over better-sqlite3 saves a user and a profile and loads the profile with its user as usual. For ORMs without such a type, declare your own type WrapperType<T> = T and use it the same way, including for @Inject(forwardRef) ⇒ OtherService constructor parameters (see ModuleRef, Circular Dependencies & Lazy Loading).

Source: NestJS: SWC - Common pitfalls

The Swagger and GraphQL CLI plugins are TypeScript compiler transformers, so a builder that does not run tsc does not run them. With the SWC builder, --type-check (or typeCheck: true) is what runs the plugins and writes a serialised metadata file that the application loads at start-up. The exact setup, with PluginMetadataGenerator, is on the OpenAPI page.

Monorepos compile with Rspack by default since NestJS 12, and the recipe says Rspack already compiles TypeScript with SWC through its built-in loader, so the swc-loader and webpack.config.js setup that the recipe still shows applies only to the deprecated webpack builder. Those projects get a single bundled file rather than one file per source file (see Project Structure & Workspaces).

Source: NestJS: SWC - CLI Plugins, NestJS: SWC - Monorepo

Tests do not go through nest build, so the test runner needs its own SWC integration to emit decorator metadata. For Vitest, unplugin-swc is a plugin in vitest.config.e2e.ts:

For Jest (CommonJS projects), the transform is @swc/jest, with the decorator settings in the project’s .swcrc:

A test that injects a service by type and calls an endpoint with supertest (a BooksController that takes a BooksService) passes with the Vitest configuration above, and, in a CommonJS project, with Jest started as node --experimental-vm-modules ./node_modules/jest/bin/jest.js, which is how the scaffolded test script runs it. The same Vitest test also passes with a configuration that has no SWC plugin at all: Vitest 4.1 runs on Vite 8, which transforms TypeScript with Oxc and emits the metadata from tsconfig.json. That is why the book-era advice "Vitest needs SWC for decorators" is no longer universally true; the plugin remains the recipe’s recommendation because it keeps the behaviour independent of the Vite version and compiles tests the way production is compiled. The details, including the failure on older Vitest, are on Testing. Remember that supertest 7 needs the default import (import request from 'supertest'), and that SWC does not type-check the tests either.

Source: NestJS: SWC - Vitest, NestJS: SWC - Jest + SWC

The recipe targets CommonJS projects and the Nest CLI’s webpack builder. In NestJS 12 that builder is deprecated (the CLI prints a deprecation notice) and the recipe’s own warning says new projects should prefer Rspack, but it still works in a CommonJS project with @nestjs/cli 12.0.8. Install the packages the CLI asks for (it names them when one is missing, including fork-ts-checker-webpack-plugin):

Add webpack-hmr.config.js to the project root. The CLI calls the function with its default webpack options and the webpack module, and the function returns the extended configuration:

webpack/hot/poll?100 is the HMR runtime that polls for updates every 100 ms, nodeExternals keeps node_modules out of the bundle (except that runtime), and RunScriptWebpackPlugin starts the bundle once and lets HMR do the rest, hence autoRestart: false. Then the entry file registers the hot-module callbacks:

The two details that look unnecessary are what prevent EADDRINUSE on reload: app.close() is asynchronous but webpack does not await the dispose callback, so the promise is stashed on module.hot.data and awaited by the next instance, and forceCloseConnections makes the old server drop keep-alive connections. Run it with the CLI’s webpack flags:

With a controller that returned { message: 'v1', pid: process.pid }, changing the string to v2 while the watcher ran produced this, and the next curl returned {"message":"v2","pid":26162}, the same process id as before the edit:

Source: NestJS: Hot reload - With CLI

The Rspack builder is the supported direction, and its configuration function has the same shape, except that the second argument is the @rspack/core module. The recipe has no Rspack variant; this one is adapted from the webpack recipe and targets the same kind of CommonJS project. Two differences: Rspack’s own HMR runtime lives at @rspack/core/hot/poll, and Rspack has no WatchIgnorePlugin (new rspack.WatchIgnorePlugin(…​) throws "is not a constructor"), so the output directory is excluded through watchOptions.ignored instead.

The main.ts is the same as above. Select the builder and the configuration on the command line, or in nest-cli.json with the object form of builder (the CLI documentation names builder.options.configPath as the replacement for the deprecated webpackConfigPath):

Both forms behave the same way. After the same v1 to v2 edit the process keeps its id, the response changes, and the log shows Rspack 2.2.8 compiled successfully in 27 ms followed by [HMR] Update applied.

Source: NestJS: Hot reload, NestJS: CLI usage - nest build

New projects are ESM, and this is where HMR is awkward. In an ESM project ("type": "module"), the webpack variant does not start at all; the CLI refuses with The webpack compiler does not support ESM projects ("type": "module" in package.json). Please use rspack instead by setting "builder": "rspack" in your nest-cli.json compilerOptions, or use --builder rspack on the command line. The Nest repository contains an ESM hot-reload sample (sample/34-hmr-esm, see the samples table below) whose script uses the same webpack flags and a .cjs configuration; check it against your CLI version before relying on it.

Rspack HMR in an ESM project (an import.meta.webpackHot check in main.ts, the HMR runtime kept out of the externals, output.publicPath set to ./) starts the application and compiles an update in about 31 ms, but the update itself fails in Node.js with [HMR] Update failed: Error [ERR_MODULE_NOT_FOUND]: Cannot find module '…​/dist/main.<hash>.hot-update.json.mjs' and the old code keeps serving. That setup is not a recommendation: for ESM projects use watch mode with the SWC builder, (its restart loop is shown on the CLI page), and use HMR where a CommonJS project with webpack or Rspack already exists.

The recipe’s own warnings apply too. A bundler does not copy assets (such as .graphql files) to dist, and a bundle does not support static glob paths such as the entities property of TypeOrmModule, so list classes explicitly. Application state (caches, in-memory sessions) is lost on every HMR cycle, as with a restart. And a configuration that works for nest build --watch is a development tool only: build production artefacts without the HMR entries.

Source: NestJS: Hot reload

Nest has no built-in abstraction for it, so the recipe builds one with three parts: a module that provides one AsyncLocalStorage instance, a middleware that opens the context, and any service that reads it. Middleware is the first thing a request reaches, so the store is visible in guards, pipes, interceptors, controllers and exception filters (see Middleware and Request Lifecycle):

When a test sends 20 concurrent requests, each with its own x-user-id, through the module, the artificial random delay makes them interleave, and every response carries the id of its own request:

The first line is the response to the request with x-user-id: u3, the second the response to a request without the header. On the Fastify adapter the same module returned {"userId":"fast-1","books":["Dune (shelved by fast-1)"]} for x-user-id: fast-1; the middleware receives the underlying request object on both platforms, so only the types in its signature differ. The pattern was introduced in Injection Scopes and the request-id variant appears in Logging.

Source: NestJS: Async local storage - Custom implementation, Node.js: AsyncLocalStorage

The limits are the ones the documentation warns about. It hides the data flow (a service now depends on something the constructor does not show), so keep the store small and avoid a catch-all object. It covers only the entry points you wrap: a cron job, a queue consumer or a message handler runs outside the request’s run() call and sees undefined. And outside any context als.getStore() returns undefined, so code that can run both ways must handle that (the example above falls back to 'anonymous').

nestjs-cls (a third-party package maintained outside the Nest core team; "CLS" stands for continuation-local storage) removes the boilerplate: a ClsModule that opens the context for you, an injectable and typed ClsService, request ids, and initialisers for transports other than HTTP. The package version here is 7.0.1, which supports NestJS 10 to 12. The first example uses four of its features at once: a typed store, a context opened by an interceptor instead of a middleware, a proxy provider, and a request id.

A request with x-user-id: ann and x-tenant: acme returned the following (with a fresh UUID each time), on both Express and Fastify:

The choices in this module are worth explaining:

Source: NestJS: Async local storage - NestJS CLS, nestjs-cls repository

Beyond HTTP, a background job or a message handler can open its own context with the @UseCls() decorator on an async method:

Calling run('acme') returned {"id":"job-f3585543-2d67-45cd-8265-513314256281","tenant":"acme"}. The decorator needs the module to be initialised (in a test, await moduleRef.init() after compile()); without that, the first call failed with this.beforeSetupHooks is not iterable, because the plugin hooks are registered during module initialisation.

In unit tests the ClsService is an ordinary provider, so it can be mocked. To use the real one, import the static ClsModule (which provides only the service) and wrap the call under test in runWith(), passing a hand-made store:

Calling ClsService outside any context did not throw: cls.isActive() was false and get('tenant') and getId() returned undefined.

Source: NestJS: Async local storage - Testing

If the application is instrumented with NestJS Observe (the pre-1.0 @nestjs/observe package, set up on the Health Checks & Observability page), it already maintains an AsyncLocalStorage store for every request, job and message it traces, and TracerService exposes it through setAttribute() and getAttribute(). There is no module or middleware to write, and the store exists wherever Observe traces an operation, not only on HTTP:

The application was created with NestFactory.create(CatalogModule, { instrument: ObserveInstrument }). Two concurrent requests with different x-user-id headers returned {"userId":"ann","traceId":"01a0fdb6-ed38-7b21-a7c4-acfa9344bff6"} and {"userId":"bob","traceId":"01a0fdb6-ed3c-740a-a24f-9cf87050cd3b"}: each saw its own value and its own trace id (a stand-in HTTP server received the telemetry; the hosted dashboard was not used). The API key pair comes from configuration, never from source. getAttribute() and setAttribute() throw outside a traced context, while currentTraceId() returns null; and as noted on the observability page, TracerService<Store> needs the store type to be a type alias, because an interface has no index signature and TypeScript 6 rejects it.

Source: NestJS: Async local storage - NestJS Observe, NestJS: Observability - Manual instrumentation