@nestjs/serve-static

@nestjs/serve-static is the official NestJS module for serving static assets — typically a built single-page application — directly from a Nest server without a separate web server or reverse proxy. It plugs into the existing Express or Fastify HTTP adapter that the Nest app already uses, so no extra runtime dependency is added beyond the adapter-specific static-file middleware.

The module detects which underlying HTTP adapter (Express or Fastify) the application is running on via an internal loader abstraction, and registers the appropriate static-serving middleware automatically. It supports serving multiple root paths, custom render paths, and excluding specific routes (such as API prefixes) from being intercepted by the static handler, configurable through both forRoot() and forRootAsync().

What You Get

• ServeStaticModule.forRoot() and forRootAsync() for static or dependency-driven configuration
• Automatic detection of the underlying HTTP adapter (Express or Fastify) with dedicated loader implementations for each
• Support for multiple static root paths registered simultaneously
• Route exclusion so API endpoints aren’t shadowed by the static file handler
• A no-op loader fallback so the module degrades gracefully when no supported adapter is present

Common Use Cases

• Serving a built React/Vue/Angular SPA bundle directly from the same NestJS server that exposes the app’s REST API
• Deploying a full-stack app as a single process/container without a separate Nginx or static-hosting layer
• Excluding /api (or similar) route prefixes from static file interception in combined frontend+backend deployments
• Switching between Express and Fastify adapters without changing static-file-serving configuration

Under The Hood

Architecture

ServeStaticModule (in lib/serve-static.module.ts) is a dynamic Nest module implementing OnModuleInit; on init it resolves the app’s HttpAdapterHost and delegates to an AbstractLoader implementation selected by serve-static.providers.ts — ExpressLoader, FastifyLoader, or a NoopLoader fallback when no recognized adapter is present — each loader registering the adapter-native static middleware with the module’s configured root paths and exclusions.

Tech Stack

TypeScript module with @fastify/static, express, and fastify all declared as optional peer dependencies (only one is required at runtime depending on the app’s adapter), plus path-to-regexp as the sole hard runtime dependency for route-exclusion pattern matching. Testing uses Vitest with a full e2e suite under tests/e2e/ exercising both express-adapter.e2e-spec.ts and fastify-adapter.e2e-spec.ts against a real sample Nest app in tests/src/.

Code Quality

Unlike some smaller official Nest modules, this repo carries genuine end-to-end tests: a sample controller/module/main.ts under tests/src/ is booted with supertest against both the Express and Fastify adapters to verify static files are actually served and routes are excluded correctly, rather than relying on unit tests of mocked internals alone. Source files remain small and single-purpose, consistent with other official @nestjs/* modules.

API Design The module follows NestJS’s now-familiar forRoot()/forRootAsync() dynamic-module convention, so existing Nest developers can configure it with zero new concepts — pass a root path (default client) and optional exclusion patterns. Adapter detection is fully automatic, meaning the same configuration code works whether the app runs on Express or Fastify, which removes an entire class of adapter-specific configuration that would otherwise fall on the developer.