Static Hosting

Deploy your Nuxt application to static hosting services using pre-rendering or static site generation (SSG).

Static hosting allows you to deploy your Nuxt application to any static file hosting service without requiring a Node.js server. Nuxt offers two approaches to static hosting.

Static Site Generation (SSG)

Static site generation with ssr: true pre-renders routes of your application at build time. This is the default behavior when running nuxt generate.

Benefits of SSG

SEO Optimized

Fully rendered HTML pages are immediately available to search engines

Fast Loading

No server processing required, instant page loads from CDN

Cost Effective

Deploy to free or low-cost static hosting services

Scalable

CDN distribution handles any traffic volume

Generate Your Site

1. Run the generate command

   Use the nuxt generate command to build and pre-render your application:

   npm

   npx nuxt generate
   
2. Review the output

   The generated files will be in the .output/public directory:

   .output/public/
   ├── index.html
   ├── about.html
   ├── _nuxt/              # JavaScript and CSS bundles
   ├── _payload.json       # Serialized data for client-side navigation
   └── 200.html            # SPA fallback for dynamic routes
   └── 404.html            # Error page
   
3. Test locally

   Preview your static site locally before deployment:

   npx serve .output/public
   
4. Deploy

   Upload the .output/public directory to your static hosting provider.

SSG Configuration

Configure SSG behavior in your nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  ssr: true, // Enable server-side rendering for pre-rendering
  
  nitro: {
    prerender: {
      // Crawl all linked pages
      crawlLinks: true,
      // Explicitly add routes
      routes: ['/sitemap.xml', '/robots.txt'],
      // Ignore specific routes
      ignore: ['/admin', '/private'],
    },
  },
})

Fallback Pages

Nuxt generates fallback pages for static hosting:

200.html (SPA Fallback)

The /200.html file serves as a single-page app fallback for dynamic routes that weren’t pre-rendered. Configure your static host to serve this file for unknown routes.

Netlify (_redirects)

/*    /200.html   200

404.html (Error Page)

The /404.html file is served when a route doesn’t exist. Most static hosts serve this automatically.

You may need to configure your static hosting provider to properly serve these fallback pages. Check your provider’s documentation for SPA configuration.

Client-Side Only Rendering

If you don’t want to pre-render your routes, you can create a static single-page application (SPA) by setting ssr to false:

nuxt.config.ts

export default defineNuxtConfig({
  ssr: false,
})

This will output an .output/public/index.html entrypoint and JavaScript bundles like a classic client-side Vue.js application.

You will lose many SEO benefits by disabling SSR. Instead, consider using <ClientOnly> components to wrap portions of your site that cannot be server-rendered.

When to Use SPA Mode

Use client-side only rendering when:

• Your app is behind authentication
• You’re building an admin dashboard or internal tool
• SEO is not a concern
• You need to minimize build time

Popular Static Hosting Providers

Deploy your static Nuxt site to these popular providers:

Netlify

Deploy to Netlify

Netlify provides zero-config deployment for Nuxt:

1. Connect your Git repository
2. Netlify auto-detects Nuxt and configures build settings
3. Build command: npm run generate
4. Publish directory: .output/public

netlify.toml:

[build]
  command = "npm run generate"
  publish = ".output/public"

[[redirects]]
  from = "/*"
  to = "/200.html"
  status = 200

Vercel

Deploy to Vercel

Vercel has built-in Nuxt support:

1. Import your project from Git
2. Vercel auto-detects Nuxt
3. Click “Deploy”

vercel.json:

{
  "buildCommand": "npm run generate",
  "outputDirectory": ".output/public",
  "routes": [
    { "handle": "filesystem" },
    { "src": "/(.*)", "dest": "/200.html" }
  ]
}

Cloudflare Pages

Deploy to Cloudflare Pages

Deploy to Cloudflare’s global CDN:

1. Connect your Git repository
2. Build command: npm run generate
3. Build output directory: .output/public

Redirects (_redirects):

/*    /200.html   200

GitHub Pages

Deploy to GitHub Pages

Deploy to GitHub Pages with GitHub Actions:

.github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npm run generate
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./.output/public

Advanced Configuration

Custom Base URL

If your site is deployed to a subdirectory, configure the base URL:

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    baseURL: '/my-app/',
    cdnURL: 'https://cdn.example.com',
  },
})

Asset Optimization

Optimize static assets for better performance:

nuxt.config.ts

export default defineNuxtConfig({
  nitro: {
    compressPublicAssets: true,
  },
  
  vite: {
    build: {
      cssCodeSplit: true,
      rollupOptions: {
        output: {
          manualChunks: {
            vendor: ['vue', 'vue-router'],
          },
        },
      },
    },
  },
})

Cache Headers

Configure cache headers for different file types:

nuxt.config.ts

export default defineNuxtConfig({
  routeRules: {
    '/_nuxt/**': { headers: { 'cache-control': 'max-age=31536000' } },
    '/images/**': { headers: { 'cache-control': 'max-age=86400' } },
  },
})

Troubleshooting

404 errors on refresh

Your static host needs to be configured to serve /200.html for unknown routes. Check your provider’s SPA configuration.

Missing pages after generation

Ensure pages are discoverable:

• Link to them from other pages
• Add them to nitro.prerender.routes
• Use the prerenderRoutes() function

API calls failing

Static sites cannot make server API calls. Use:

• External APIs
• Serverless functions
• Pre-fetch data during build with useAsyncData

Environment variables not working

Client-side apps can’t access server environment variables. Use runtimeConfig.public for client-accessible values.

Next Steps

Prerendering

Learn advanced prerendering techniques

Node.js Server

Deploy with full SSR capabilities