.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Why Fastify for production
When you benchmark Fastify against Express, the numbers speak. Fastify handles 2 to 3 times more requests per second than Express in real-world conditions. On simple hello-world tests, Fastify hits 114,195 requests per second while Express tops out around 20,000. That gap widens with realistic workloads: database queries, authentication and file uploads. Fastify's advantage comes from its performance-first architecture, not random optimization luck.
Beyond speed, Fastify includes features that Express makes you bolt on separately. Structured logging arrives built-in via Pino, JSON schema validation prevents bad data from reaching your handlers and the plugin system is explicit rather than middleware chaos. You don't need Morgan or Winston or express-validator. They're already there.
The trade-off is real though. Fastify's plugin ecosystem is smaller than Express. If you need 50 middleware packages and all of them exist for Express first, you might wait or write your own. For APIs and microservices where you control the dependency tree, Fastify is worth the switch. For monoliths that rely on a sprawling middleware ecosystem, Express may be easier.
Understanding Fastify 5 breaking changes
Fastify 5 wasn't a minor release. The framework dropped backward compatibility with a purpose: removing deprecated patterns and cleaning up the API surface. If you're migrating from v4, several changes will break your code.
The listen syntax change is critical
This is the first thing that will bite you. Fastify 5 removed support for the variadic listen() signature. In v4, you could call listen() with port as a number, or a mix of arguments. Fastify 5 requires the object form exclusively.
Old v4 syntax (now broken):
fastify.listen(3000, '0.0.0.0', (err, address) => {
if (err) throw err;
});New v5 syntax (required):
fastify.listen({ port: 3000, host: '0.0.0.0' }, (err, address) => {
if (err) throw err;
});This matters on a VPS because Fastify defaults to 127.0.0.1 (localhost only) if you don't set host. Your Nginx reverse proxy sits on the same machine and can't reach localhost. You need host: '0.0.0.0' to listen on all interfaces. Skip it and you get "connection refused" from Nginx with no clear reason why.
Host binding gotcha: 0.0.0.0 vs 127.0.0.1
A common mistake: setting host to 0.0.0.0 in development and wondering why your laptop can access the app but your VPS can't. On a VPS, 0.0.0.0 is correct. It means "listen on all interfaces." Your Nginx on 127.0.0.1 can reach it. Your external requests to your domain can reach it (through Nginx).
127.0.0.1 only listens on loopback. Nginx can proxy to it from the same machine. But it's a foot-gun in VPS setups where you might later try to expose Fastify directly. Always use 0.0.0.0 for production unless you have a specific reason not to.
Other v5 migration notes
Beyond listen(), Fastify 5 changed how the logger option works. In v4, you could pass a custom logger. In v5, you pass only Pino options or true. If you built a custom logger integration, you'll need to rewrite it.
The request.connection property is gone. Use request.socket instead. JSON schema validation now requires a full schema for querystring, params and body. The jsonShortHand option was removed. Reference the official Fastify v5 migration guide for the complete list of 20+ breaking changes.
Setting up a production Fastify 5 app
Basic server setup
Start with a fresh Node project and install Fastify:
npm init -y
npm install fastify
mkdir src
touch src/server.jsCreate src/server.js with the v5 listen syntax:
import Fastify from 'fastify';
const fastify = Fastify({
logger: {
level: 'info'
}
});
fastify.get('/', async (request, reply) => {
return { status: 'ok', timestamp: new Date().toISOString() };
});
fastify.listen({ port: 3000, host: '0.0.0.0' }, (err, address) => {
if (err) {
fastify.log.error(err);
process.exit(1);
}
fastify.log.info(`Server running at ${address}`);
});
export default fastify;Test locally with node src/server.js. You should see the log message and the app should respond to curl http://localhost:3000.
TypeScript compilation strategies
TypeScript in production requires a build step. Your source stays in src/, your compiled JavaScript goes to dist/. Never run .ts files directly with node in production. You have three strategies.
The simplest is tsc with a tsconfig.json:
npm install -D typescript @types/node
npx tsc --initEdit tsconfig.json:
{
"compilerOptions": {
"target": "ES2020",
"module": "ES2020",
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"moduleResolution": "node",
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}Add to package.json scripts:
"build": "tsc",
"start": "node dist/server.js"For faster builds, use tsup (single-file bundling):
npm install -D tsup
npm run build # configured as: "tsup src/server.ts --format esm --outDir dist"Or esbuild for maximum speed with tree-shaking:
npm install -D esbuild
npm run build # configured as: "esbuild src/server.ts --bundle --platform=node --target=es2020 --outfile=dist/server.js"tsc is slowest but most compatible. tsup is faster and handles ESM well. esbuild is fastest but less mainstream. For production, any of them work. Pick based on your build time budget.
Project structure for production
Organize your code so deployment is clean:
fastify-api/
src/
server.ts
routes/
users.ts
posts.ts
plugins/
db.ts
auth.ts
services/
userService.ts
dist/ # compiled output, not in git
logs/ # PM2 will create this
.env # production secrets, chmod 600
.env.example # template for developers
.gitignore
ecosystem.config.js
package.json
tsconfig.jsonKeep your routes in separate files and register them as plugins. Your main server.ts stays lean, just initialization and plugin loading. Services handle business logic. Plugins add features like database connections.
PM2 ecosystem configuration
Cluster mode setup
Create ecosystem.config.js in your project root. This file tells PM2 how to run Fastify:
module.exports = {
apps: [
{
name: 'fastify-api',
script: './dist/server.js',
instances: 'max',
exec_mode: 'cluster',
env: {
NODE_ENV: 'production',
PORT: 3000
},
env_staging: {
NODE_ENV: 'staging',
PORT: 3001
}
}
]
};
The key line is instances: 'max', which tells PM2 to spawn one worker process per CPU core. On a 4-core VPS, that's 4 Fastify processes. exec_mode: 'cluster' means PM2 uses the Node.js cluster module to distribute incoming connections across workers. You don't need to write cluster code yourself. PM2 does the plumbing.
Memory limits and resource management
Production Fastify can consume memory. Set limits so one runaway process doesn't eat your whole VPS:
module.exports = {
apps: [
{
name: 'fastify-api',
script: './dist/server.js',
instances: 'max',
exec_mode: 'cluster',
max_memory_restart: '600M',
node_args: '--max-old-space-size=512',
env: {
NODE_ENV: 'production'
}
}
]
};max_memory_restart tells PM2: if this process exceeds 600 MB of resident memory, restart it. --max-old-space-size=512 sets the V8 heap limit to 512 MB per process. On a 4-core machine with 4 workers, that's 2 GB heap plus overhead. Tune these based on your VPS RAM and app behavior.
Log configuration
PM2 can capture stdout and stderr from your app. But you're using Pino, which logs to stdout as JSON. Tell PM2 where to put those logs and how to rotate them:
module.exports = {
apps: [
{
name: 'fastify-api',
script: './dist/server.js',
instances: 'max',
exec_mode: 'cluster',
error_file: './logs/error.log',
out_file: './logs/combined.log',
log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
merge_logs: true,
env: {
NODE_ENV: 'production'
}
}
]
};In cluster mode, all workers write to the same file. merge_logs: true ensures their output doesn't interleave in weird ways. Log rotation is better handled by an external tool like logrotate or pino-roll, since PM2's log files can grow unbounded.
Nginx reverse proxy configuration
Upstream with keepalive
Create /etc/nginx/sites-available/fastify-api:
upstream fastify_backend {
least_conn;
server 127.0.0.1:3000;
keepalive 32;
}
server {
listen 80;
server_name yourdomain.com;
location / {
proxy_pass http://fastify_backend;
proxy_http_version 1.1;
proxy_set_header Connection '';
proxy_buffering off;
proxy_cache off;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $host;
}
}least_conn tells Nginx to send requests to the server with the fewest active connections. That's better load balancing than round-robin when requests have varied processing times. keepalive 32 means Nginx keeps 32 idle HTTP connections to the backend. This avoids TCP handshake overhead on every request. Set Connection '' to tell the backend we support HTTP/1.1 connection reuse.
Proxy headers explained
Your Fastify app sits behind Nginx. Nginx receives the client's request, then proxies it internally to Fastify on 127.0.0.1:3000. Fastify sees the connection coming from 127.0.0.1, not the real client. Your code won't know the real client IP unless you set proxy headers.
X-Real-IP tells Fastify the real client IP address. X-Forwarded-For is a list of IPs the request passed through. X-Forwarded-Proto tells Fastify whether the original request was HTTP or HTTPS (important for req.protocol). Set Host to the original Host header so virtual hosting works. Without these, your logging and authentication logic will break.
SSL with Certbot
Get a free HTTPS certificate from Let's Encrypt:
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.comCertbot rewrites your Nginx config, adding HTTPS listeners and redirecting HTTP to HTTPS automatically. It also sets up a systemd timer for auto-renewal. Your Fastify app still runs on port 3000 internally. Nginx handles encryption at the edge.
Verify renewal works:
sudo certbot renew --dry-runGzip compression: Nginx vs Fastify
You can gzip in Nginx or in Fastify. Nginx is better. Let Nginx handle it:
server {
listen 80;
server_name yourdomain.com;
gzip on;
gzip_types text/plain application/json application/javascript text/css;
gzip_min_length 1000;
gzip_comp_level 6;
gzip_vary on;
location / {
proxy_pass http://fastify_backend;
# ... proxy headers ...
}
}Nginx compresses responses before sending them to clients. Your Fastify app doesn't spend CPU on compression. And if you have multiple Fastify processes, they each skip the compression step. You could add @fastify/compress to Fastify itself for situations where Nginx isn't in front (development, testing), but production almost always has Nginx doing compression.
Pino logging configuration
Development vs production settings
Development logging should be pretty and human-readable. Production logging should be structured JSON for aggregation tools. Configure Fastify's logger based on NODE_ENV:
const loggerConfig = process.env.NODE_ENV === 'production'
? { level: 'info' }
: {
level: 'debug',
transport: {
target: 'pino-pretty',
options: {
colorize: true,
singleLine: true,
translateTime: 'HH:MM:ss Z'
}
}
};
const fastify = Fastify({ logger: loggerConfig });In production, Pino outputs raw JSON. In development, pino-pretty makes it readable with colors and timestamps. Install pino-pretty locally for development only:
npm install -D pino-prettyLog levels and transports
Pino has five log levels: fatal, error, warn, info, debug. In production, set level: 'info' to skip debug logs and reduce noise. In development, use 'debug' to see everything.
A transport is where Pino sends logs. The default transport writes to stdout. You can add more:
const fastify = Fastify({
logger: {
level: 'info',
transport: {
targets: [
{
level: 'info',
target: 'pino/file',
options: { destination: '/var/log/fastify/app.log' }
},
{
level: 'error',
target: 'pino/file',
options: { destination: '/var/log/fastify/error.log' }
}
]
}
}
});This sends info+ logs to app.log and error+ logs to error.log. In practice, log files grow fast. Use external rotation or pipe logs to a service like Datadog or New Relic.
Structured JSON logging
Pino logs as JSON by default. Each log line is an object with timestamp, level, message and context fields:
{"level":30,"time":1713897600000,"pid":1234,"hostname":"vps","msg":"GET / 200 OK"}This is goldmiin for log aggregation. Services like Datadog, ELK and Splunk parse JSON logs and let you query by field. You can filter: "show me all error logs from the user-service in the last hour" or aggregate: "what's the p95 response time for POST /api/users."
Fastify logs requests automatically. You don't need middleware. Add custom logs in your route handlers:
fastify.post('/users', async (request, reply) => {
fastify.log.info({ userId: request.user.id }, 'Creating new user');
// ... handler code ...
fastify.log.debug({ newUserId }, 'User created');
return { created: true };
});Log rotation with pino-roll or logrotate
Log files grow. Without rotation, they consume your entire disk. Pino-roll is a transport that rotates files by size or time:
npm install pino-roll
const fastify = Fastify({
logger: {
level: 'info',
transport: {
target: 'pino-roll',
options: {
file: '/var/log/fastify/app.log',
size: '100M', // rotate at 100MB
frequency: 'daily' // also rotate daily
}
}
}
});Or use system logrotate. Create /etc/logrotate.d/fastify-api:
/var/log/fastify/*.log {
daily
rotate 7
compress
delaycompress
notifempty
create 0640 nodeapp nodeapp
sharedscripts
postrotate
pm2 reload fastify-api --update-env > /dev/null 2>&1 || true
endscript
}This rotates logs daily, keeps 7 days of backups and compresses old ones. The postrotate script tells PM2 to reload the app so it opens a new log file.
JSON schema validation
Request validation schemas
Fastify validates requests against JSON schemas. Requests that don't match are rejected with a 400 error automatically. Define a schema for a route:
const createUserSchema = {
body: {
type: 'object',
required: ['email', 'name'],
properties: {
email: { type: 'string', format: 'email' },
name: { type: 'string', minLength: 1, maxLength: 100 },
age: { type: 'integer', minimum: 0, maximum: 150 }
},
additionalProperties: false
},
querystring: {
type: 'object',
properties: {
sendEmail: { type: 'boolean' }
}
}
};
fastify.post('/users', { schema: createUserSchema }, async (request, reply) => {
// request.body is already validated
return { created: true, userId: 123 };
});If the client sends invalid JSON (missing required fields, wrong types), Fastify rejects it before your handler runs. No need for custom validation middleware. The schema acts as both documentation and runtime guard.
Response serialization
Define a response schema to ensure your API always returns the right shape:
const createUserSchema = {
body: { /* ... */ },
response: {
200: {
type: 'object',
properties: {
created: { type: 'boolean' },
userId: { type: 'integer' }
}
},
400: {
type: 'object',
properties: {
message: { type: 'string' }
}
}
}
};
fastify.post('/users', { schema: createUserSchema }, async (request, reply) => {
// Must return matching shape
return { created: true, userId: 123 };
});Fastify also uses the response schema to serialize JSON efficiently. It strips extra fields and formats values according to the schema. This is faster than JSON.stringify plus filtering.
Shared schemas with dollar ref
Reuse schema fragments with $ref. Define them once and reference them:
fastify.addSchema({
$id: 'User',
type: 'object',
properties: {
id: { type: 'integer' },
email: { type: 'string', format: 'email' },
name: { type: 'string' }
}
});
const listUsersSchema = {
response: {
200: {
type: 'array',
items: { $ref: 'User#' }
}
}
};
fastify.get('/users', { schema: listUsersSchema }, async (request, reply) => {
return [
{ id: 1, email: '[email protected]', name: 'Alice' },
{ id: 2, email: '[email protected]', name: 'Bob' }
];
});$ref: 'User#' references the schema with $id: 'User'. You define the User shape once and reuse it everywhere. Reduces duplication and makes updates easier.
Fastify plugins for production
Helmet for security headers
Install and register @fastify/helmet to set HTTP security headers:
npm install @fastify/helmet
import helmet from '@fastify/helmet';
fastify.register(helmet, {
contentSecurityPolicy: {
directives: {
defaultSrc: ["'self'"],
scriptSrc: ["'self'", "'unsafe-inline'"],
styleSrc: ["'self'", "'unsafe-inline'"],
imgSrc: ["'self'", 'data:', 'https:']
}
}
});Helmet sets headers like Content-Security-Policy, X-Frame-Options and Strict-Transport-Security. These prevent XSS, clickjacking and MIME sniffing attacks. There's no performance cost. It's a single registration that hardens your surface significantly.
Rate limiting with fastify-rate-limit
Prevent brute force and DoS attacks:
npm install @fastify/rate-limit
import rateLimit from '@fastify/rate-limit';
fastify.register(rateLimit, {
max: 100,
timeWindow: '15 minutes',
cache: 10000,
allowList: ['127.0.0.1'],
redis: 'redis://localhost:6379' // optional, for multi-server
});This limits each IP to 100 requests per 15 minutes. Without redis, rate limits are per-server in-memory (fine for single server). With Redis, limits are shared across all servers in a cluster.
For per-route limits:
fastify.post('/auth/login',
{ rateLimit: { max: 5, timeWindow: '15 minutes' } },
async (request, reply) => {
// this route is limited to 5 attempts per 15 minutes
}
);CORS configuration
If your Fastify API serves browsers from a different domain:
npm install @fastify/cors
import cors from '@fastify/cors';
fastify.register(cors, {
origin: ['https://yourdomain.com', 'https://app.yourdomain.com'],
credentials: true,
methods: ['GET', 'POST', 'PUT', 'DELETE']
});In production, never use origin: '*'. Whitelist specific domains. This prevents malicious sites from making requests on behalf of your users.
Compression support
If Nginx isn't compressing (unusual), you can do it in Fastify:
npm install @fastify/compress
import compress from '@fastify/compress';
fastify.register(compress, {
encodings: ['gzip', 'deflate'],
threshold: 1024 // only compress > 1KB
});But in production with Nginx, let Nginx handle compression. It's centralized and can compress responses from any backend.
Monitoring with Prometheus
PM2 provides basic monitoring with pm2 monit and pm2 logs. For production, use Prometheus and Grafana to track CPU, memory, request latency and error rates. See the Prometheus and Grafana guide for detailed setup. Fastify integrates cleanly with Prometheus via the fastify-metrics plugin, which exposes metrics on /metrics. Pino's structured logs integrate with log aggregators like Datadog or ELK.
Zero-downtime deploys
When you push a new version, use PM2's graceful reload:
npm run build
pm2 reload fastify-api --update-envPM2 restarts one worker at a time. Nginx keeps routing traffic to the running workers while others restart. Your app goes down for zero milliseconds. For full CI/CD automation, see the zero-downtime deploy guide.
Fastify vs Express: four dimensions
Performance: Fastify handles 2 to 3x more requests per second than Express. The difference grows with realistic workloads. Express is still fast enough for most apps. Choose Fastify if throughput matters.
Built-ins: Fastify includes logging (Pino) and validation (JSON schema) out of the box. Express requires you to add Morgan, Winston, express-validator and similar packages. Fewer dependencies means fewer security audits and fewer breaking changes.
Plugins: Fastify's plugin system is explicit. You register plugins and they have clear lifecycles. Express middleware is simpler to write but less structured. Complex middleware chains in Express become hard to reason about.
Ecosystem: Express has vastly more middleware and integrations. If you need a specific feature and it exists for Express first, you might wait weeks for the Fastify version. For popular patterns, both frameworks have libraries.
Choose Fastify if you want speed, structured defaults and explicit plugin semantics. Choose Express if you value familiarity, middleware variety or rapid prototyping. Both run fine on a VPS with PM2 and Nginx.
Troubleshooting
Fastify app only accepts localhost connections
You set host: '127.0.0.1' or omitted the host parameter. Fastify defaults to 127.0.0.1 for security. On a VPS, Nginx can't reach localhost. Set host: '0.0.0.0' in your listen call.
CORS errors when accessing from browser
Your browser is on a different domain than your API. Register @fastify/cors and whitelist the origin. Never use origin: '*' in production.
JSON schema validation fails unexpectedly
Your handler is returning an object that doesn't match the response schema. Check the response schema definition and make sure you're returning the exact shape Fastify expects. Use additionalProperties: false to catch extra fields.
Memory keeps growing
Set max_memory_restart in PM2 config to restart processes when they exceed a threshold. Also monitor your code for memory leaks. Use clinic.js or node --inspect to profile memory usage.
