Does NestJS Work With Cloudflare Pages?
NestJS can run on Cloudflare Pages via Workers, but it requires significant adaptation since Pages is edge-first and doesn't natively support traditional Node.js server frameworks.
Quick Facts
How NestJS Works With Cloudflare Pages
NestJS is a full-featured Node.js framework designed for traditional server deployments, while Cloudflare Pages is a JAMstack platform optimized for static sites and serverless functions. Direct compatibility is limited because NestJS expects a persistent Node.js runtime, but Cloudflare Pages runs code on Workers with strict execution constraints (CPU time limits, memory restrictions, no file system access). You can deploy NestJS to Cloudflare Pages using the `@nestjs/platform-fastify` adapter combined with Wrangler, but you'll lose many NestJS features that depend on traditional server capabilities. The recommended approach is using NestJS as a backend API on Workers while serving static frontend assets through Pages, creating a hybrid architecture. Alternatively, use Cloudflare Pages Functions for lightweight request handlers instead of deploying full NestJS instances. If you need NestJS's full feature set with global distribution, consider Vercel, Netlify, or Railway instead, which provide better Node.js runtime support.
Best Use Cases
NestJS on Cloudflare Pages Functions
npm install -g wrangler && npm install @nestjs/core @nestjs/common fastify// src/index.ts
import { NestFactory } from '@nestjs/core';
import { FastifyAdapter } from '@nestjs/platform-fastify';
import { AppModule } from './app.module';
export default {
async fetch(request: Request, env: any) {
const app = await NestFactory.create(AppModule, new FastifyAdapter());
await app.init();
const instance = app.getHttpAdapter().getInstance();
return instance.routing(request);
}
};
// wrangler.toml
name = "nestjs-pages"
main = "src/index.ts"
compatibility_date = "2024-01-01"
[env.production]
vars = { DATABASE_URL = "your-db-url" }Known Issues & Gotchas
NestJS modules with filesystem dependencies (file uploads, caching) fail on Cloudflare Workers due to no persistent disk access
Fix: Use Cloudflare R2 for storage, KV for caching, and adapt your services to async I/O patterns compatible with Workers
TypeORM and traditional ORMs experience cold starts and connection pooling issues on Workers
Fix: Switch to Prisma with connection pooling via Cloudflare's data backend, or use REST APIs to existing databases
Decorators and reflection-heavy NestJS patterns add bundle size overhead, exceeding Worker script limits
Fix: Tree-shake unused decorators, minimize imports, and consider using Fastify adapter over Express for smaller footprint
Environment variables must be configured through wrangler.toml, not .env files
Fix: Use `wrangler secret` CLI commands for sensitive values and reference via `env` context in handlers
Alternatives
- •Vercel + Express/Fastify: Traditional Node.js serverless with better cold start times and persistent connections
- •AWS Lambda + API Gateway + NestJS: Full control over runtime environment with native Node.js support
- •Remix + Cloudflare Pages: Purpose-built for edge deployment with better DX and no framework impedance mismatch
Resources
Related Compatibility Guides
Explore more compatibility guides