NestJS 12.6.0 was released on 20 November 2026. It’s a minor release, but it brings three things Node.js backend developers will notice straight away: NestFactory.create() now infers the application type from the adapter, the WebSocket adapter gets an opt-in graceful shutdown, and the gRPC server’s graceful shutdown now has a time limit. There are also several behaviour changes worth checking before you upgrade.
This tutorial covers each feature with working code, then lists the changes that could affect existing apps.
Upgrade first
Update all @nestjs/* packages together so their versions match:
npm install @nestjs/[email protected] @nestjs/[email protected] \
@nestjs/[email protected] @nestjs/[email protected] \
@nestjs/[email protected] @nestjs/[email protected]
Only install the platform and microservice packages you actually use. Run your test suite before and after so you can tell new failures from old ones.
1. The app type is inferred from the adapter
Before 12.6, if you used Fastify you had to pass the application type as a generic, or you would get the generic INestApplication type and lose Fastify-specific methods:
// Before 12.6
const app = await NestFactory.create<NestFastifyApplication>(
AppModule,
new FastifyAdapter(),
);
Now the type comes from the adapter, so this is enough:
// main.ts (NestJS 12.6)
import { NestFactory } from '@nestjs/core';
import { FastifyAdapter } from '@nestjs/platform-fastify';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule, new FastifyAdapter());
// app is typed as NestFastifyApplication, so Fastify-specific
// methods are available without a type argument
await app.listen(3000, '0.0.0.0');
}
bootstrap();
The release notes say the same applies to ExpressAdapter and NodeAdapter. Your existing code keeps working, because an explicit type argument is still accepted, so you can remove the generics gradually.
Custom adapters
If you maintain your own HTTP adapter, declare its application type as the fourth type argument of AbstractHttpAdapter. That is what lets NestFactory.create() infer it for your users too.
2. Graceful shutdown for the WebSocket adapter
Closing a NestJS app that uses raw WebSockets (@nestjs/platform-ws) used to drop connections abruptly. In 12.6, WsAdapter accepts two options:
gracefulShutdown,falseby default.gracePeriod, 10,000 ms by default.
With gracefulShutdown turned on, closing the application:
- stops accepting new connections (an upgrade request on a server shared with the HTTP adapter gets a 503),
- ignores new messages,
- waits up to
gracePeriodfor running message handlers and pending replies, - closes each socket with code 1001 (“going away”).
Here is a setup that turns it on and hooks it up to the process signals:
// main.ts
import { NestFactory } from '@nestjs/core';
import { WsAdapter } from '@nestjs/platform-ws';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
app.useWebSocketAdapter(
new WsAdapter(app, { gracefulShutdown: true, gracePeriod: 15_000 }),
);
// Call app.close() on SIGTERM/SIGINT so the graceful path runs
app.enableShutdownHooks();
await app.listen(3000);
}
bootstrap();
The WsAdapter constructor takes the app (or HTTP server) as its first argument and a WsAdapterOptions object as its second, which is where gracefulShutdown and gracePeriod go. Sockets still open once gracePeriod has passed are terminated.
A gateway doesn’t need any changes. Long-running handlers simply get time to finish:
// events.gateway.ts
import { SubscribeMessage, WebSocketGateway } from '@nestjs/websockets';
@WebSocketGateway()
export class EventsGateway {
@SubscribeMessage('report')
async handleReport(): Promise<{ event: string; data: string }> {
await new Promise((r) => setTimeout(r, 3_000)); // slow work
return { event: 'report', data: 'done' };
}
}
On the client side, treat close code 1001 as “server is restarting” and reconnect with a backoff, rather than showing an error.
Separately, 12.6 makes gateways reject new clients as soon as the application starts closing, even without the new option.
3. A grace period for gRPC graceful shutdown
The gRPC microservice server already had gracefulShutdown. The difference now is that it has a limit. Previously, closing waited for in-progress calls with no limit. In 12.6, calls still running after gracePeriod (10,000 ms by default) are cancelled.
// main.ts for a gRPC microservice
import { NestFactory } from '@nestjs/core';
import { MicroserviceOptions, Transport } from '@nestjs/microservices';
import { join } from 'node:path';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.createMicroservice<MicroserviceOptions>(AppModule, {
transport: Transport.GRPC,
options: {
package: 'orders',
protoPath: join(__dirname, 'orders.proto'),
gracefulShutdown: true,
gracePeriod: 60_000, // allow long streams up to 60 s to finish
},
});
app.enableShutdownHooks();
await app.listen();
}
bootstrap();
This is a behaviour change. If you run long server-streaming calls, the default 10 seconds may cut them off during deploys. The release notes suggest raising gracePeriod for long-running streams. Also make sure your orchestrator’s termination window (for example, Kubernetes terminationGracePeriodSeconds) is longer than gracePeriod, or the process will be killed before Nest finishes.
Other behaviour changes to check
These come from the “New defaults and behaviour changes” section of the release notes:
- Custom response decorators. A custom parameter decorator that gives the handler the response object now passes it unchanged, and no pipe runs on it, as with
@Res(). On Fastify such a handler used to never run. @Res({ passthrough: true })inheritance. A method that overrides such a handler with a plain@Res()no longer inheritspassthrough.- Route conflict detection with hosts. String hosts are now read as patterns, so
:tenant.example.comis reported as overlappingadmin.example.com. You may see new conflict reports. - Testing module logging.
createNestApplication()andcreateNestMicroservice()on a testing module now treatloggerandforceConsolelikeNestFactorydoes.logger: truekeeps logging on (it used to turn it off), which may make test output noisier. - Fastify bad URLs. A request whose target doesn’t start with
/(other than*and absolute-form URLs) now gets a 400 (FST_ERR_BAD_URL) instead of reaching the not-found handler. inject()responses. On the Fastify and Node platforms, responses toHEAD, and 204 or 304 responses, have no body.- Node platform charset. A
Content-Typeset withres.setHeader()getscharset=utf-8whenres.send()sends a string, as on Express.
Microservice clients fail faster
Several clients now fail pending requests with “Connection closed” instead of leaving them waiting: Kafka when its reply consumer stops or a rebalance moves its reply partition, MQTT and Redis when closed before the reply subscription is confirmed, and RabbitMQ when the broker cancels the direct reply-to consumer. If you had timeouts around these calls, you may now see errors sooner, which is generally better. Make sure your callers handle them.
Performance work
12.6 also includes performance changes: less overhead for HTTP Observable responses, an interceptor chain built without extra RxJS layers, Fastify’s built-in request hooks folded into one, and RPC, WebSocket and external params resolved without a promise. No benchmark numbers are given, so measure your own app.
Takeaway
NestJS 12.6 is an easy upgrade with a few real wins: cleaner Fastify bootstrap code thanks to adapter-based type inference, and proper graceful shutdown for WebSockets. The one change to plan for is gRPC: calls running past gracePeriod are now cancelled, so set it to match your longest stream and keep your container’s termination window longer than that.
