Nuxt Deployment Config

Nuxt Deployment Config

Target Node.js servers, edge runtimes, static hosting, or hybrid modes using Nitro presets and route rules

When to Use

• You are preparing a Nuxt app for production deployment to Vercel, Cloudflare, Netlify, or a Node server
• You need to prerender specific pages for static hosting while keeping others server-rendered
• You want ISR (Incremental Static Regeneration) — cached SSR with time-based revalidation
• You are hitting cold start latency on serverless and need edge rendering

Instructions

Selecting an output preset:

1. Set the Nitro preset via the NITRO_PRESET environment variable or in nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'vercel-edge', // or 'cloudflare-pages', 'netlify', 'node-server', etc.
  },
});

Common presets:

Preset	Target
node-server (default)	Node.js server (Docker, Railway, Render)
vercel	Vercel serverless functions
vercel-edge	Vercel Edge Network
cloudflare-pages	Cloudflare Pages + Workers
netlify	Netlify Functions
netlify-edge	Netlify Edge Functions
static	Full static export

Static prerendering:

2. Prerender specific routes at build time:

export default defineNuxtConfig({
  nitro: {
    prerender: {
      routes: ['/sitemap.xml', '/robots.txt', '/'],
      crawlLinks: true, // follow <a> tags from prerendered pages
    },
  },
});

3. Mark a page for prerendering from within the page component:

definePageMeta({ prerender: true });

4. Prerender all pages (full static site):

export default defineNuxtConfig({
  ssr: true,
  nitro: {
    prerender: { crawlLinks: true, routes: ['/'] },
  },
});

Hybrid rendering with routeRules:

5. Apply per-route rendering strategies using routeRules:

export default defineNuxtConfig({
  routeRules: {
    // Static generation at build time
    '/': { prerender: true },
    '/blog/**': { prerender: true },

    // ISR — revalidate every 60 seconds
    '/products/**': { isr: 60 },

    // Full SSR — no caching
    '/dashboard/**': { ssr: true },

    // SPA-only — no SSR
    '/admin/**': { ssr: false },

    // Redirect
    '/old-page': { redirect: '/new-page' },

    // Headers
    '/api/**': { headers: { 'cache-control': 's-maxage=3600' } },

    // CORS
    '/api/public/**': { cors: true },
  },
});

Client-only mode:

6. Disable SSR globally for a SPA deployment:

export default defineNuxtConfig({
  ssr: false,
});

Edge deployment considerations:

7. Edge runtimes (Cloudflare Workers, Vercel Edge) have no Node.js APIs. Check compatibility:
   • No fs module — use KV stores or R2/S3 for persistence
   • No process.env — use Nitro runtime config
   • Bundle size matters — avoid heavy Node.js dependencies

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'cloudflare-pages',
    // Polyfill or replace Node APIs
    externals: { traceInclude: ['./server/db.ts'] },
  },
});

Runtime config for deployment variables:

8. Never hardcode secrets. Use runtime config with environment variables:

export default defineNuxtConfig({
  runtimeConfig: {
    // Server-only (private)
    databaseUrl: process.env.DATABASE_URL,
    secretKey: process.env.SECRET_KEY,
    // Exposed to client
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE ?? '/api',
    },
  },
});

Details

Build output structure:

Running nuxt build produces .output/:

.output/
  public/    ← static assets, served directly by CDN
  server/    ← Nitro server bundle
    index.mjs  ← server entry point
    chunks/

The .output/server/index.mjs is environment-agnostic — the preset wraps it for the target platform.

ISR vs. SWR:

Both revalidate cached responses in the background:

• isr: 60 — revalidate every 60 seconds (time-based, Vercel-style)
• swr: true — stale-while-revalidate (serve cached, revalidate in background)

Prerender vs. generate:

In Nuxt 3, nuxt generate is an alias for nuxt build with the static preset. The prerender.crawlLinks option replaces the Nuxt 2 routes array generation.

Caching headers with routeRules:

The headers rule sets response headers on the Nitro server. For CDN caching, use s-maxage; for browser caching, use max-age:

'/assets/**': { headers: { 'cache-control': 'max-age=31536000, immutable' } }

When to use each rendering mode:

• Prerender — marketing pages, docs, blogs (content rarely changes, maximum CDN cache hit rate)
• ISR — product listings, news feeds (content changes periodically, acceptable staleness)
• SSR — user dashboards, personalized pages (must be fresh per request)
• SPA — admin panels, apps behind auth (SEO not needed, maximum interactivity)

Source

https://nuxt.com/docs/getting-started/deployment

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.