Implementing Hybrid Rendering in Nuxt 3 with Route Rules

The Problem: One Rendering Mode Does Not Fit All Routes

A typical application has diverse content needs: marketing pages require fast, cacheable HTML for SEO; user dashboards need private, client-side rendering to avoid leaking markup; and news feeds need near-static speed with periodic updates. Using a single global SSR (Server-Side Rendering) or SPA (Single Page Application) setting forces a trade-off between crawlability, latency, and build costs.

The solution is Hybrid Rendering. By using routeRules in Nuxt 3, you can assign a specific rendering strategy to each route pattern. This allows you to mix static pre-rendering, SSR, client-only SPA, and ISR (Incremental Static Regeneration) within a single codebase.

Desired Outcome

After configuration, your application will behave as follows:

• /blog/**: Pre-rendered at build time to static HTML files for maximum edge performance.
• /dashboard/**: Rendered entirely on the client (SPA), preventing server-side rendering of private user data.
• /news/**: Served from a cache and automatically revalidated every 60 seconds (ISR).

Prerequisites

You need Nuxt 3.8+ and a Nitro preset targeting a platform that supports your chosen strategy (e.g., Vercel, Netlify, Cloudflare Pages). While basic SSR works on any Node.js server, ISR and Static generation require a deployment target with edge/serverless functions or a persistent storage adapter to maintain cache state.

Configuring Route Rules

Define your strategies in nuxt.config.ts. Note that Nitro evaluates these rules and merges them; more specific patterns should be defined to ensure they take precedence over catch-all patterns.

export default defineNuxtConfig({
  nitro: {
    preset: 'vercel' // Example: target platform supporting ISR
  },
  routeRules: {
    // Static Site Generation (SSG) for blog posts
    '/blog/**': { static: true },
    // Client-side only (SPA) for private dashboards
    '/dashboard/**': { ssr: false },
    // Incremental Static Regeneration (ISR) for news
    '/news/**': { isr: 60 },
    // Prerender the homepage specifically
    '/': { prerender: true }
  }
})

Key Rule Definitions

• static: true: Generates HTML at build time and stores it in .output/public.
• ssr: false: Disables server rendering for the route. The server sends a minimal HTML shell, and the page hydrates entirely in the browser.
• isr: [seconds]: Enables ISR. The first request renders the page; subsequent requests serve the cached version until the TTL (Time To Live) expires.

Build and Local Verification

To verify the configuration locally, run the build and preview commands from your project root:

npx nuxi build
npx nuxi preview

Check the .output directory to confirm the rendering artifacts:

• Static routes: Look for .html files in .output/public.
• ISR routes: Look for server handlers in .output/server/routes.
• SPA routes: Confirm that no specific HTML file is generated for the path; it should rely on the main index shell.

If using TypeScript, run npx nuxi typecheck to ensure your routeRules conform to the expected Nitro configuration interfaces.

Deployment and Header Validation

Deploy to a staging environment that matches your production preset. Use curl to inspect the response headers and verify the rendering strategy is active:

curl -I https://staging.example.com/blog/post-1

Expected Header Results

Limitations and Recovery

Platform Constraints

ISR requires platform-specific support. If you use the node-server preset without an external KV or Redis storage adapter (via nitro.storage), ISR will behave like standard SSR because the cache is not persisted across server restarts.

Scaling and SEO

• Build Times: Pre-rendering thousands of static routes can significantly increase build times. For large catalogs, use ISR instead of static: true.
• SEO: Routes marked ssr: false are not pre-rendered. Search crawlers may struggle to index this content unless you use a dynamic rendering service.

Recovery Options

• ISR Fallback: If your target platform does not support ISR, change isr: 60 to ssr: true or static: true (with scheduled rebuilds) and redeploy.
• Stale Content: For ISR routes, you can trigger on-demand revalidation via the platform-specific POST endpoint (e.g., Vercel's revalidation API) to clear the cache before the TTL expires.
• Rollback: Revert the routeRules in nuxt.config.ts and redeploy. This is a configuration change and does not require database migrations.