Skip to main content
NestJS is a progressive Node.js framework designed for building scalable and maintainable server-side applications. It uses TypeScript by default and follows a structured, modular architecture inspired by Angular, making it especially well-suited for large or complex projects. With built-in support for dependency injection, decorators, and powerful abstractions for HTTP, WebSockets, and microservices, NestJS provides a robust foundation for creating clean, organized, and enterprise-grade APIs. NestJS can only be used on Application Hosting; it cannot be deployed as a static site.

​
Configuration

NestJS applications require at least an S1 pod on Sevalla to start reliably, as the framework’s initialization and compilation process demands more memory than smaller pod sizes provide.
NestJS applications are built using the NestJS CLI, which compiles TypeScript to JavaScript. Sevalla runs npm run build then npm start and the build output goes to dist/ directory. The package.json file should include the following: 
{
  "scripts": {
    "build": "nest build",
    "start": "node dist/main",
    "start:dev": "nest start --watch",
    "start:prod": "node dist/main"
  }
}

​
Environment variables

Set your environment variables directly in Sevalla. For managing them inside your NestJS application, we recommend the following best practices:
  • Use the @nestjs/config package for structured environment configuration
  • Install with: npm install @nestjs/config
  • Load .env files automatically using ConfigModule
  • Access variables through ConfigService via dependency injection
  • Validate all environment variables at startup to prevent misconfiguration
  • Never commit .env files to version control
Example ConfigModule setup: 
// src/app.module.ts
import { Module } from "@nestjs/common";
import { ConfigModule } from "@nestjs/config";

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: ".env",
    }),
  ],
})
export class AppModule {}

​
Containerization

​
Dockerfile

The build for Dockerfiles is fully customizable. We recommend the following best practices when using a Dockerfile for NestJS on Sevalla:
  • Use Alpine images - Smaller image size (~40MB vs ~900MB).
  • Multi-stage builds - Separate build and runtime dependencies.
  • Layer caching - Copy package.json before the source code.
  • Security - Run as a non-root user in production.
  • .dockerignore - Exclude unnecessary files.
# Build stage
FROM node:lts-alpine AS builder

WORKDIR /app

COPY package.json package-lock.json* ./
RUN npm ci

COPY . .
RUN npm run build

# Production stage
FROM node:lts-alpine

WORKDIR /app

COPY package.json package-lock.json* ./
RUN npm ci --only=production

COPY --from=builder /app/dist ./dist

EXPOSE 3000

ENV PORT=3000
ENV HOST=0.0.0.0
ENV NODE_ENV=production

CMD ["node", "dist/index.js"]

​
Nixpacks

You can customize the Nixpacks build process by defining a nixpacks.toml file and using Nixpacks-specific environment variables. This allows you to fine-tune how dependencies are installed, how your application is built, and which runtime settings are applied. You can control the Node.js version used during the build by using an .nvmrc file, the engines field in package.json, or the NIXPACKS_NODE_VERSION environment variable. If none are set, Nixpacks defaults to Node.js 18. The following is an example nixpacks.toml configuration for NestJS: 
# nixpacks.toml

[phases.setup]
nixPkgs = ["nodejs_22"]

[phases.install]
cmds = ["npm ci"]

[phases.build]
cmds = ["npm run build"]

[start]
cmd = "npm start"
The following is an example nixpacks.toml for NestJS with additional system dependencies: 
# nixpacks.toml
[phases.setup]
# Add additional system packages if needed (e.g., for image processing)
nixPkgs = ["nodejs_22", "imagemagick", "ffmpeg"]

[phases.install]
cmds = ["npm ci"]

[start]
cmd = "npm start"

​
Buildpacks

Buildpacks automatically detect your project’s lock file and install dependencies using the appropriate package manager. With Buildpacks, you cannot modify the underlying build phases or control how dependencies are installed; this is determined entirely by your project’s structure and configuration. However, you can influence the final runtime behavior by defining the correct start script in your package.json, which Buildpacks will use when launching your NestJS application.

​
CDN

Sevalla provides a premium, Cloudflare-powered CDN for Application Hosting at no additional cost. To get the most out of Sevalla’s CDN when deploying your NestJS application, we recommend the following best practices:
  • Enable the CDN for all production applications.
  • Set appropriate Cache-Control headers on API routes to ensure proper caching behavior.
  • Purge the CDN cache after deploying critical updates to avoid serving stale content.
  • Use versioned URLs for static assets, for example /static/app.v123.js .

​
Optimizing NestJS for CDN

​
Static files with cache headers

// src/main.ts
import { NestFactory } from "@nestjs/core";
import { NestExpressApplication } from "@nestjs/platform-express";
import { join } from "path";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule);

  // Serve static files with caching
  app.useStaticAssets(join(__dirname, "..", "public"), {
    prefix: "/static/",
    maxAge: "1y",
    immutable: true,
    setHeaders: (res, path) => {
      res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
    },
  });

  await app.listen(process.env.PORT || 3000);
}
bootstrap();

​
Edge caching

Edge caching stores your Sevalla site cache on Cloudflare’s 260+ global data centers, delivering responses from the location nearest to each visitor for faster performance. To maximize the benefits of Sevalla’s Edge Caching for your NestJS application, we recommend the following best practices:
  • Set appropriate Cache-Control headers in loaders to control caching behavior.
  • Combine edge caching with the CDN for a complete caching strategy.

​
Optimizing NestJS for edge caching

// src/products/products.controller.ts
import { Controller, Get, Header } from "@nestjs/common";
import { ProductsService } from "./products.service";

@Controller("api/products")
export class ProductsController {
  constructor(private readonly productsService: ProductsService) {}

  // API with edge caching
  @Get()
  @Header("Cache-Control", "public, max-age=60, s-maxage=3600")
  async findAll() {
    return this.productsService.findAll();
  }
}

// src/user/user.controller.ts
import { Controller, Get, Header } from "@nestjs/common";
import { UserService } from "./user.service";

@Controller("api/user")
export class UserController {
  constructor(private readonly userService: UserService) {}

  // User-specific data (don't cache)
  @Get("profile")
  @Header("Cache-Control", "private, no-cache")
  async getProfile() {
    return this.userService.getProfile();
  }
}

​
Cache-Control

With Sevalla’s Cloudflare integration,Cache-Controlheaders are respected at the edge, giving you precise control over how content is cached and served globally. The following are some common directives you can use in your NestJS application:
  • public, s-maxage=3600 - Caches the response on the CDN for 1 hour, improving performance for frequently accessed content.
  • public, max-age=31536000, immutable - Ideal for versioned static assets, allowing them to be cached for up to 1 year with no revalidation.
  • private - Prevents CDN caching and ensures the response is only cached by the end user’s browser, for personalized or sensitive data.
Sevalla does not yet support the stale-while-revalidate Cache-Control directive. To prevent unexpected caching behavior, we recommend not using this directive in your API or asset caching settings.

​
Health checks

Ensure your application remains available during deployments by implementing health checks:
  • Always implement health checks for production applications.
  • Keep checks lightweight; responses should complete in under 1 second.
  • Verify critical dependencies (e.g., databases, Redis) using @nestjs/terminus as part of the checks.

​
Basic health check

// src/health/health.controller.ts
import { Controller, Get } from "@nestjs/common";

@Controller("health")
export class HealthController {
  @Get()
  check() {
    return {
      status: "ok",
      timestamp: new Date().toISOString(),
      runtime: "Node.js",
      version: process.version,
    };
  }
}

​
Graceful shutdown

NestJS has built-in support for graceful shutdown with enableShutdownHooks() : 
// src/main.ts
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Enable graceful shutdown hooks
  app.enableShutdownHooks();

  await app.listen(process.env.PORT || 3000);
}
bootstrap();
Implement OnModuleDestroy for custom cleanup logic for custom cleanup logic: 
// src/app.service.ts
import { Injectable, OnModuleDestroy } from "@nestjs/common";
import { DataSource } from "typeorm";

@Injectable()
export class AppService implements OnModuleDestroy {
  constructor(private dataSource: DataSource) {}

  async onModuleDestroy() {
    console.log("Gracefully shutting down...");
    await this.dataSource.destroy();
    console.log("Database connections closed");
  }
}