Nuxt Deployment — Deploy to Static Hosting, Node.js Servers, and Serverless Platforms

In this tutorial, you will learn about Nuxt Deployment. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn Nuxt deployment — deploy to Netlify, Vercel, Cloudflare, and Node.js servers with static generation, server-side rendering, and serverless configurations.

In this lesson, you'll understand how to prepare and deploy a Nuxt application to various hosting platforms with the correct rendering mode and configuration.

What You'll Learn

How to build Nuxt for different deployment targets, deploy static sites to Netlify and Cloudflare Pages, deploy SSR apps to Node.js servers and Vercel, configure environment variables per platform, and set up CI/CD pipelines.

Why It Matters

The wrong deployment setup causes broken routes, missing server-side features, and slow load times. Each hosting platform has specific requirements — understanding them ensures your app works correctly in production.

Real-World Use

A content site with 50,000 daily visitors deploys as a static site on Cloudflare Pages with Nuxt's SSG mode, achieving 99.9% uptime, zero server costs, and sub-100ms load times globally through CDN caching.

flowchart TD
    A[Nuxt App] --> B{Build Target}
    B -->|Static| C[SSG - generate]
    B -->|SSR| D[Node Server]
    B -->|Serverless| E[Serverless Function]
    C --> F[Netlify]
    C --> G[Cloudflare Pages]
    C --> H[GitHub Pages]
    D --> I[VPS / Dedicated]
    D --> J[Docker Container]
    E --> K[Vercel]
    E --> L[AWS Lambda]
    E --> M[Netlify Functions]
    style A fill:#00dc82,color:#fff

Static Site Deployment (SSG)

Generate a fully static site:

npm run generate

This creates a dist/ directory with HTML, CSS, and JS files ready for any static host.

For Nuxt config:

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    prerender: {
      routes: ['/', '/about', '/blog', '/contact'],
      crawlLinks: true
    }
  }
});

Deploy to any static host — just point the host to dist/.

Netlify Deployment

Netlify supports both static and serverless modes:

// nuxt.config.ts — Netlify serverless
export default defineNuxtConfig({
  nitro: {
    preset: 'netlify' // or 'netlify-edge' for edge functions
  }
});

# netlify.toml
[build]
  command = "npm run build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "20"

[[redirects]]
  from = "/api/*"
  to = "/.netlify/functions/:splat"
  status = 200

npx netlify deploy --prod --dir=dist

Expected output: A Nuxt app deployed to Netlify with serverless API routes and automatic HTTPS.

Vercel Deployment

Vercel is optimized for Nuxt with zero configuration:

// nuxt.config.ts — Vercel preset (default)
export default defineNuxtConfig({
  nitro: {
    preset: 'vercel'
  }
});

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

For static deployment on Vercel:

npm run generate
vercel --prod --prebuilt

Expected output: Automatic deployment with SSR, ISR, and Edge Functions support. Vercel detects Nuxt and applies optimal settings automatically.

Node.js Server Deployment

Deploy SSR mode on your own server:

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'node-server'
  }
});

npm run build

// server.js — custom Node.js server
const { loadNuxt, buildNuxt } = require('nuxt');

async function start() {
  const nuxt = await loadNuxt({ dev: false });
  await buildNuxt(nuxt);
  
  const { listener } = nuxt.server;
  listener.listen(3000, () => {
    console.log('Nuxt app listening on port 3000');
  });
}

start();

Docker deployment:

FROM node:20-alpine
WORKDIR /app
COPY .output ./
EXPOSE 3000
CMD ["node", "./server/index.mjs"]

Expected output: A production Nuxt SSR server running on port 3000, ready for Load Balancing and reverse proxy configuration.

Cloudflare Pages Deployment

Deploy to Cloudflare's global network:

// nuxt.config.ts — Cloudflare
export default defineNuxtConfig({
  nitro: {
    preset: 'cloudflare-pages',
    cloudflare: {
      pages: {
        routes: [
          { pattern: '/api/*', execute: 'api' }
        ]
      }
    }
  }
});

# Build
npm run build

# Deploy via Wrangler CLI
npx wrangler pages deploy .output/public

Expected output: A Nuxt app distributed across Cloudflare's 330+ global locations with automatic CDN caching and edge network routing.

Environment Variables in Production

Configure per-platform environment variables:

# Netlify — set in UI or via CLI
npx netlify env:set NUXT_PUBLIC_API_BASE https://api.production.com
npx netlify env:set NUXT_API_SECRET @/path/to/secret

# Vercel — set in UI or via CLI
vercel env add NUXT_PUBLIC_API_BASE production

# Cloudflare — set in wrangler.toml or UI
# [vars]
# NUXT_PUBLIC_API_BASE = "https://api.production.com"

Expected output: Environment-specific configuration without hardcoded values in source code, managed through each platform's secret management.

CI/CD Pipeline

Automate deployment with GitHub Actions:

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - run: npm run build
        env:
          NUXT_PUBLIC_API_BASE: ${{ vars.API_BASE }}
          NUXT_API_SECRET: ${{ secrets.API_SECRET }}

      - name: Deploy to Netlify
        uses: nwtgck/actions-netlify@v3
        with:
          publish-dir: '.output/public'
          production-branch: main
          github-token: ${{ secrets.GITHUB_TOKEN }}
          deploy-message: 'Deploy from GitHub Actions'
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

Expected output: Automatic deployments triggered by push to main, with environment variables injected from GitHub secrets and variables.

Common Mistakes

1. Not matching the Nitro preset to the hosting platform: Each platform requires a specific preset. Deploying a vercel build to Netlify causes function routing errors. Always set the correct preset in nuxt.config.ts.

2. Forgetting to pre-render dynamic routes for SSG: SSG only generates routes it discovers during the build. Use prerender.routes in nitro config to explicitly list dynamic routes like /blog/post-1, /blog/post-2.

3. Missing _headers or _redirects for SPA fallback: On static hosts, page refreshes on dynamic routes return 404. Add redirect rules to fall back to index.html for client-side routing.

4. Not setting Node.js version: Some platforms default to older Node versions (12, 14) that don't support Nuxt 3. Set NODE_VERSION = "20" in your platform's environment settings.

5. Exposing server config in client bundle: Private runtimeConfig values are server-only. In SSR mode, ensure you're not accidentally passing private values to client components through props or state.

Practice Questions

1. What is the difference between npm run build and npm run generate? Answer: build creates a server-rendered app (SSR) that requires a Node.js server. generate creates a fully static site with all pages pre-rendered as HTML files.

2. Why does the Nitro preset matter for deployment? Answer: Each platform has different routing, function execution, and caching models. The preset generates the correct output format (Cloudflare Workers, Vercel Serverless, Netlify Functions) for the target platform.

3. How do you handle environment-specific API URLs in production? Answer: Use runtime config with environment variables per platform. Set NUXT_PUBLIC_API_BASE to the appropriate value in each environment's configuration UI or env file.

4. What is the purpose of nitro.prerender.crawlLinks? Answer: It tells Nuxt to follow links from pre-rendered pages during SSG and automatically generate HTML for linked pages, reducing the manual route list needed.

Challenge

Set up a complete deployment pipeline with: static generation for content pages, SSR mode for authenticated routes, deployment to two platforms (Netlify for production, Vercel for staging), environment-specific configuration with secrets management, CI/CD that runs tests and deploys on merge to main, and a rollback Strategy using deployment versioning.

Mini Project

Create a deployment-ready Nuxt application with: SSG mode configured with pre-rendered routes, separate .env.staging and .env.production files, a Dockerfile for containerized SSR deployment, a GitHub Actions workflow for automated deployment, a netlify.toml with redirect rules and function configuration, and a deployment checklist document that includes pre-deployment testing, environment variable validation, and rollback procedures.

FAQ

What's Next

Build a complete Nuxt Mini Project that combines everything you've learned — routing, composables, data fetching, server routes, authentication, error handling, and deployment.