Deployment Guide

vinext applications can be deployed to multiple environments. Cloudflare Workers is the primary target with first-class support, but other platforms are also possible.

Quick Deploy to Cloudflare Workers

The fastest way to deploy is using the built-in deploy command:

vinext deploy

This single command:

Detects your router type (App Router or Pages Router)
Auto-generates missing configuration files
Installs required dependencies
Runs the production build
Deploys to Cloudflare Workers

See the Cloudflare Workers guide for detailed deployment instructions.

Production Build

Before deploying to any platform, create a production build:

npm run build

Or use the vinext CLI directly:

vinext build

Build Output

vinext generates different build outputs based on your router type:

App Router Build

Multi-environment build with three separate bundles:

dist/
├── rsc/              # React Server Components environment
│   └── index.js      # RSC request handler
├── ssr/              # Server-Side Rendering environment  
│   └── index.js      # SSR renderer
└── client/           # Browser environment
    ├── index.js      # Client hydration entry
    └── assets/       # CSS, fonts, images

The RSC entry handles routing, the SSR entry renders HTML, and the client bundle provides hydration and interactivity.

Pages Router Build

dist/
├── server/           # Server bundle
│   └── index.js      # SSR + API routes handler
└── client/           # Browser bundle
    ├── pages/        # Per-page chunks
    └── assets/       # Static assets

Deployment Targets

Cloudflare Workers (Recommended)

Cloudflare Workers is the primary deployment target with full feature support: ✅ Zero cold starts - Workers run globally with instant startup
✅ Edge computing - Deploy to 300+ cities worldwide
✅ ISR via KV - Built-in cache handler for incremental static regeneration
✅ Image optimization - Native Cloudflare Images integration
✅ One-command deploy - vinext deploy handles everything Supported Features:

App Router with React Server Components
Pages Router with SSR and API routes
Middleware and rewrites
Server Actions
ISR (Incremental Static Regeneration)
Streaming SSR
Image optimization via Cloudflare Images

See Cloudflare Workers Deployment for complete instructions.

Static Export

Generate a fully static site that can be deployed to any static hosting provider:

// next.config.js
module.exports = {
  output: 'export',
};

Then build:

vinext build

This produces a dist/ directory with static HTML, CSS, and JavaScript files. Deploy to:

Cloudflare Pages
Vercel
Netlify
GitHub Pages
AWS S3 + CloudFront
Any static file server

Limitations:

No server-side rendering (SSR)
No API routes
No dynamic routes without generateStaticParams() (App Router) or getStaticPaths() (Pages Router)
No ISR

See Static Export Guide for details.

Node.js Server

Run a production Node.js server locally or in a container:

vinext start

This starts a production server with:

SSR (Server-Side Rendering)
API routes (Pages Router) / Route handlers (App Router)
Middleware
Response compression (gzip/brotli)

Use Cases:

Testing production builds locally
Deploying to VM-based hosts
Docker containers
Traditional Node.js hosting

Options:

vinext start --port 3000          # Custom port
vinext start --hostname 0.0.0.0   # Bind to all interfaces

The Node.js production server is less optimized than Cloudflare Workers deployment. Workers is the recommended production target.

Custom Deployment

For other platforms, you can import the production build programmatically:

App Router

import handler from './dist/rsc/index.js';

// Your platform's request handler
export default {
  async fetch(request: Request): Promise<Response> {
    return handler.fetch(request);
  }
};

Pages Router

import { renderPage, handleApiRoute } from './dist/server/index.js';

export default async function handler(request: Request) {
  const url = new URL(request.url);
  
  if (url.pathname.startsWith('/api/')) {
    return handleApiRoute(request, url.pathname + url.search);
  }
  
  return renderPage(request, url.pathname + url.search, null);
}

Environment-Specific Configuration

Use different configs for different environments:

Development

// vite.config.ts
import { defineConfig } from 'vite';
import vinext from 'vinext';

export default defineConfig({
  plugins: [vinext()],
  server: {
    port: 3000,
  },
});

Production (Cloudflare Workers)

// vite.config.ts
import { defineConfig } from 'vite';
import vinext from 'vinext';
import { cloudflare } from '@cloudflare/vite-plugin';

export default defineConfig({
  plugins: [
    vinext(),
    cloudflare({
      viteEnvironment: {
        name: 'rsc',
        childEnvironments: ['ssr'],
      },
    }),
  ],
});

Conditional Config

import { defineConfig } from 'vite';
import vinext from 'vinext';
import { cloudflare } from '@cloudflare/vite-plugin';

export default defineConfig(({ mode }) => {
  const isProduction = mode === 'production';
  
  return {
    plugins: [
      vinext(),
      isProduction && cloudflare(),
    ].filter(Boolean),
    build: {
      minify: isProduction,
      sourcemap: !isProduction,
    },
  };
});

CI/CD Integration

GitHub Actions (Cloudflare Workers)

name: Deploy to Cloudflare Workers

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Build and Deploy
        run: npx vinext deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

GitHub Actions (Static Export)

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Build
        run: npm run build
        
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

Performance Optimization

Bundle Size

vinext produces smaller client bundles than Next.js due to:

More aggressive tree-shaking (Vite/Rollup)
Lighter client-side router
Minimal framework overhead

Typical savings: 20-30% smaller gzipped bundles.

Build Speed

Benchmarks show vinext builds are significantly faster than Next.js:

Development cold start: ~2-3x faster
Production build: ~1.5-2x faster
HMR updates: Near-instant

See benchmarks.vinext.workers.dev for detailed metrics.

Code Splitting

Vite automatically code-splits:

Per-route chunks (lazy loaded)
Shared dependency extraction
CSS code splitting
Dynamic imports

No configuration needed—it works out of the box.

Health Checks

Add a health check endpoint for monitoring:

App Router

// app/health/route.ts
export async function GET() {
  return Response.json({ status: 'ok' });
}

Pages Router

// pages/api/health.ts
export default function handler(req, res) {
  res.status(200).json({ status: 'ok' });
}

Rollback Strategy

Cloudflare Workers deployments support instant rollback:

# List recent deployments
wrangler deployments list

# Rollback to a specific version
wrangler rollback <deployment-id>

For other platforms, maintain multiple deployment slots or use your hosting provider’s rollback features.

Monitoring

Cloudflare Analytics

Workers deployments include built-in analytics:

Request volume and errors
CPU time per request
Edge response times
Geographic distribution

Access via the Cloudflare Dashboard.

Custom Logging

// app/middleware.ts
import { NextResponse } from 'next/server';

export function middleware(request) {
  const start = Date.now();
  const response = NextResponse.next();
  const duration = Date.now() - start;
  
  console.log({
    method: request.method,
    url: request.url,
    duration,
    status: response.status,
  });
  
  return response;
}

Troubleshooting

Build Failures

Error: Cannot find module during build Solution: Ensure all dependencies are installed:

npm ci  # Clean install from package-lock.json

Memory Issues

Error: JavaScript heap out of memory Solution: Increase Node.js memory limit:

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

Deploy Failures (Cloudflare)

Error: Authentication error during deploy Solution: Set your Cloudflare API token:

export CLOUDFLARE_API_TOKEN="your-token-here"
vinext deploy

Generate tokens at: https://dash.cloudflare.com/profile/api-tokens

Large Bundle Sizes

Problem: Client bundle is larger than expected Solution: Analyze the bundle:

npm install --save-dev rollup-plugin-visualizer

Add to vite.config.ts:

import { visualizer } from 'rollup-plugin-visualizer';

export default defineConfig({
  plugins: [
    vinext(),
    visualizer({ open: true }),
  ],
});

Next Steps

Cloudflare Workers

Complete guide to deploying on Cloudflare Workers

Static Export

Generate static HTML for any hosting provider

Configuration

Advanced configuration options

Build Pipeline

Build optimization and performance

Get Started

Core Concepts

Guides

Documentation Index

​Deployment Guide

​Quick Deploy to Cloudflare Workers

​Production Build

​Build Output

​App Router Build

​Pages Router Build

​Deployment Targets

​Cloudflare Workers (Recommended)

​Static Export

​Node.js Server

​Custom Deployment

​App Router

​Pages Router

​Environment-Specific Configuration

​Development

​Production (Cloudflare Workers)

​Conditional Config

​CI/CD Integration

​GitHub Actions (Cloudflare Workers)

​GitHub Actions (Static Export)

​Performance Optimization

​Bundle Size

​Build Speed

​Code Splitting

​Health Checks

​App Router

​Pages Router

​Rollback Strategy

​Monitoring

​Cloudflare Analytics

​Custom Logging

​Troubleshooting

​Build Failures

​Memory Issues

​Deploy Failures (Cloudflare)

​Large Bundle Sizes

​Next Steps

Cloudflare Workers

Static Export

Configuration

Build Pipeline

Build docs developers (and LLMs) love

Deployment Guide

Quick Deploy to Cloudflare Workers

Production Build

Build Output

App Router Build

Pages Router Build

Deployment Targets

Cloudflare Workers (Recommended)

Static Export

Node.js Server

Custom Deployment

App Router

Pages Router

Environment-Specific Configuration

Development

Production (Cloudflare Workers)

Conditional Config

CI/CD Integration

GitHub Actions (Cloudflare Workers)

GitHub Actions (Static Export)

Performance Optimization

Bundle Size

Build Speed

Code Splitting

Health Checks

App Router

Pages Router

Rollback Strategy

Monitoring

Cloudflare Analytics

Custom Logging

Troubleshooting

Build Failures

Memory Issues

Deploy Failures (Cloudflare)

Large Bundle Sizes

Next Steps