Nuxt Static Generation — Building Static Sites with nuxt generate

Learn how to generate static sites with Nuxt 3 using nuxt generate for pre-rendering, hybrid rendering, and deployment to static CDN hosting.

In this lesson, you'll understand how to generate static HTML from your Nuxt application, configure routes for generation, and deploy to static hosting.

What You'll Learn

How to run nuxt generate, configure routes for generation, handle dynamic routes, and understand hybrid rendering modes.

Why It Matters

Static generation produces HTML files that can be served from a CDN with no server costs. It's the fastest and most scalable deployment option.

flowchart LR
    A[Nuxt App] --> B[nuxt generate]
    B --> C[Static HTML]
    B --> D[JavaScript]
    B --> E[CSS]
    C --> F[CDN]
    D --> F
    E --> F
    style B fill:#00dc82,color:#fff

Basic Static Generation

npm run generate

Output: Nuxt crawls your pages, generates static HTML for each, and outputs to dist/. The site works without a server.

Configuring Routes

Specify dynamic routes for pre-rendering:

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    prerender: {
      routes: [
        '/',
        '/about',
        '/blog',
        '/blog/getting-started',
        '/blog/advanced-nuxt'
      ],
      crawlLinks: true  // Auto-discover links
    }
  }
});

Dynamic Route Generation

Pre-render dynamic routes from data:

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    prerender: {
      routes: async () => {
        const posts = await $fetch('https://api.example.com/posts');
        return posts.map(post => `/blog/${post.slug}`);
      }
    }
  }
});

Output: Each blog post gets a pre-rendered HTML file at /blog/post-slug/index.html.

Hybrid Rendering

Mix static and server-rendered routes:

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    // Static (pre-rendered)
    '/': { prerender: true },
    '/blog/**': { prerender: true },
    
    // Server-side rendered
    '/dashboard/**': { ssr: true },
    
    // Client-side only (SPA)
    '/admin/**': { ssr: false },
    
    // API routes (server)
    '/api/**': { ssr: true },
    
    // Redirect
    '/old-blog/**': { redirect: '/blog/**' }
  }
});

Client-Side Rendering Only

Create an SPA mode:

// nuxt.config.ts
export default defineNuxtConfig({
  ssr: false  // Disable SSR, run as SPA
});

In SPA mode, the initial request returns a shell HTML with no content. JavaScript renders everything client-side.

Static Generation with useFetch

useFetch works differently in static mode:

<script setup>
// In static mode, data is fetched at build time
const { data } = await useFetch('/api/posts', {
  // Data is fetched during generate and embedded in HTML
});
</script>

For client-only data fetching in static sites:

<script setup>
const { data } = await useFetch('/api/posts', {
  lazy: true,    // Fetch on client after hydration
  server: false  // Don't fetch during SSR/generate
});
</script>

Common Mistakes

1. Not pre-rendering dynamic routes: Without specifying routes, dynamic pages aren't generated. Use crawlLinks: true or explicit route lists.
2. Using server routes with static hosting: Server routes need a server runtime. For static sites, use client-side API calls to external services.
3. Not handling client-only fallbacks: Pages with ssr: false need a fallback loading state for the initial page load.
4. Missing 404.html: Generate a static 404 page for proper error handling on CDNs.
5. Forgetting crawlLinks: true: Without it, only explicitly listed routes are pre-rendered. Crawling discovers linked pages automatically.

Practice Questions

1. What command generates a static Nuxt site? Answer: npm run generate or npx nuxi generate. It outputs static files to dist/.

2. How do you pre-render dynamic routes like /blog/:slug? Answer: Use nitro.prerender.routes with an async function that returns all possible slugs.

3. What does routeRules allow you to do? Answer: Define per-route rendering modes: prerender, SSR, CSR, or redirect. Each route can have a different Strategy.

4. What happens when ssr: false is set? Answer: The app runs in SPA mode. No server-side rendering occurs. The initial page is a shell that loads JavaScript to render content.

Challenge

Create a Nuxt site with hybrid rendering: static homepage and blog, SSR dashboard with user-specific data, client-only admin panel, and server API routes. Verify each route renders correctly.

Mini Project

Build a Nuxt site that's fully statically generated: blog with 20+ posts from Markdown, product pages from a CMS, documentation pages, and a sitemap. Deploy to Cloudflare Pages and test all routes work without a server.

FAQ

What's Next

Learn about Nuxt SSR, SSG, and SPA Modes for a comprehensive comparison of Nuxt's rendering modes.