vinext start - vinext

Starts a production HTTP server to serve the output from vinext build. Supports SSR, static file serving, compression, and middleware.

Usage

vinext start [options]

You must run vinext build before vinext start. The start command serves the built output from the dist/ directory.

Options

--port

number

default:"3000"

Port to listen on. Can also use the short form -p. Defaults to the PORT environment variable if set.

vinext start --port 8080
vinext start -p 8080

# Or using environment variable
PORT=8080 vinext start

--hostname

string

default:"0.0.0.0"

Hostname to bind to. Can also use the short form -H.

vinext start --hostname localhost
vinext start -H 127.0.0.1

Default is 0.0.0.0 (all interfaces) in production, unlike dev mode which defaults to localhost.

--help

flag

Show help for this command. Can also use -h.

vinext start --help

Behavior

Server Implementation

The production server is implemented in server/prod-server.ts and provides:

// From cli.ts:273-281
const { startProdServer } = await import(
  "./server/prod-server.js"
);

await startProdServer({
  port,
  host,
  outDir: path.resolve(process.cwd(), "dist"),
});

Features:

Static asset serving: Serves files from dist/client/
SSR rendering: Server-side renders pages on request
API route handling: Routes /api/* requests to server handlers
Compression: Gzip and Brotli compression for text-based responses
Streaming SSR: Supports React 18 streaming for App Router

Request Handling

The production server handles requests in this order:

Middleware/Proxy (if exists)
Redirects (from next.config)
Rewrites (from next.config)
Static assets (dist/client/)
API routes (/api/*)
Page routes (SSR)
404 page (if no match)

Response Compression

The server automatically compresses responses:

// From prod-server.ts:54-69
const COMPRESSIBLE_TYPES = new Set([
  "text/html",
  "text/css",
  "text/javascript",
  "application/javascript",
  "application/json",
  "image/svg+xml",
  "application/manifest+json",
]);

Encoding preference: Brotli > Gzip > Deflate > Identity Minimum threshold: 1024 bytes (files smaller than 1KB are not compressed)

SSR Output

For Pages Router, the server loads the SSR entry:

// dist/server/entry.js exports:
export { renderPage, handleApiRoute }

For App Router, the server loads the RSC entry:

// dist/server/index.js exports:
export default {
  async fetch(request: Request): Promise<Response>
}

Examples

Basic Usage

Start production server on default port (3000):

vinext build
vinext start

Output:

vinext start  (port 3000)

  Production server running at:
  ➜  http://0.0.0.0:3000/

Custom Port

Start on port 8080:

vinext start --port 8080

Or:

vinext start -p 8080

Using Environment Variables

PORT=8080 vinext start

Or add to .env.production:

PORT=8080

Bind to Localhost Only

For security on shared hosts:

vinext start --hostname localhost

Production npm Script

Add to package.json:

{
  "scripts": {
    "build": "vinext build",
    "start": "vinext start",
    "prod": "vinext build && vinext start"
  }
}

Then:

npm run prod

Deployment

Node.js Deployment

For traditional Node.js hosting:

# Build on your CI server
vinext build

# Deploy dist/ directory and node_modules
# Start with:
vinext start --port 80 --hostname 0.0.0.0

Docker Deployment

# Dockerfile
FROM node:20-slim

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy built files
COPY dist ./dist
COPY next.config.* ./
COPY vite.config.* ./

# Start production server
EXPOSE 3000
CMD ["npx", "vinext", "start"]

Build and run:

docker build -t my-app .
docker run -p 3000:3000 my-app

Cloudflare Workers

For Cloudflare Workers, use vinext deploy instead:

vinext deploy

This builds and deploys in one command. See the deploy command for details.

Process Management

Using PM2

For production deployments with auto-restart:

npm install -g pm2

# Start with PM2
pm2 start "vinext start" --name my-app

# View logs
pm2 logs my-app

# Restart
pm2 restart my-app

# Stop
pm2 stop my-app

Using systemd

Create /etc/systemd/system/my-app.service:

[Unit]
Description=My vinext App
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/my-app
ExecStart=/usr/bin/npx vinext start
Restart=on-failure
Environment=NODE_ENV=production
Environment=PORT=3000

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable my-app
sudo systemctl start my-app
sudo systemctl status my-app

Performance

Response Times

Typical server response times:

Route Type	Cold Start	Warm
Static asset	less than 1ms	less than 1ms
SSR page (cached)	5-15ms	2-5ms
SSR page (fresh)	20-50ms	10-20ms
API route	5-20ms	2-10ms

Benchmarks from a medium-complexity app on modern hardware. Actual times vary by complexity.

Compression Impact

Typical compression ratios:

Content Type	Original	Gzip	Brotli
HTML	100KB	20KB (80%)	18KB (82%)
JavaScript	500KB	150KB (70%)	130KB (74%)
CSS	50KB	12KB (76%)	10KB (80%)
JSON	100KB	10KB (90%)	8KB (92%)

Caching Strategy

The server sets these cache headers:

// Static assets (hashed filenames)
Cache-Control: public, max-age=31536000, immutable

// HTML pages (SSR)
Cache-Control: public, max-age=0, must-revalidate

// API routes (no cache by default)
Cache-Control: no-store

Troubleshooting

”dist/ directory not found”

You forgot to build first:

vinext build
vinext start

Port Already in Use

Another process is using the port:

# Find what's using port 3000
lsof -ti:3000

# Kill the process
kill -9 $(lsof -ti:3000)

# Or use a different port
vinext start --port 3001

Pages Not Loading (404)

Check the build output:

ls dist/client
ls dist/server

Ensure both directories exist and contain files.

High Memory Usage

The server loads all pages into memory. For very large apps:

Increase Node.js heap size:

NODE_OPTIONS="--max-old-space-size=4096" vinext start

Or deploy to Cloudflare Workers (no memory limits):
```
vinext deploy
```

Monitoring

Health Check Endpoint

Add a health check page:

// pages/api/health.ts
export default function handler() {
  return Response.json({ status: 'ok' })
}

Then monitor:

curl http://localhost:3000/api/health
# {"status":"ok"}

Access Logs

The production server logs all requests to stdout:

GET /about 200 12ms
GET /api/users 200 45ms
POST /api/contact 201 67ms

Redirect logs to a file:

vinext start > access.log 2>&1

CLI

Module Shims

Configuration

Cloudflare

Documentation Index

​Usage

​Options

​Behavior

​Server Implementation

​Request Handling

​Response Compression

​SSR Output

​Examples

​Basic Usage

​Custom Port

​Using Environment Variables

​Bind to Localhost Only

​Production npm Script

​Deployment

​Node.js Deployment

​Docker Deployment

​Cloudflare Workers

​Process Management

​Using PM2

​Using systemd

​Performance

​Response Times

​Compression Impact

​Caching Strategy

​Troubleshooting

​”dist/ directory not found”

​Port Already in Use

​Pages Not Loading (404)

​High Memory Usage

​Monitoring

​Health Check Endpoint

​Access Logs

​Next Steps

deploy Command

Deployment Guide

Build docs developers (and LLMs) love

Usage

Options

Behavior

Server Implementation

Request Handling

Response Compression

SSR Output

Examples

Basic Usage

Custom Port

Using Environment Variables

Bind to Localhost Only

Production npm Script

Deployment

Node.js Deployment

Docker Deployment

Cloudflare Workers

Process Management

Using PM2

Using systemd

Performance

Response Times

Compression Impact

Caching Strategy

Troubleshooting

”dist/ directory not found”

Port Already in Use

Pages Not Loading (404)

High Memory Usage

Monitoring

Health Check Endpoint

Access Logs

Next Steps