Nuxt 3 Route Rules: Designing Hybrid Rendering for Optimal Performance

Problem & Takeaway

Modern web apps need a mix of static, dynamic and frequently updated pages. Nuxt 3’s routeRules let you pick a rendering strategy per route without writing multiple server‑side handlers. The key is to keep a single codebase, respect data‑access boundaries, and verify that each rule behaves as expected in the chosen deployment target.

Requirements

• Marketing and blog pages should be static for fast CDN delivery.
• Personal dashboards must render on each request with user‑specific data.
• News articles update hourly but can be served from cache between updates.
• Product catalog pages are semi‑dynamic: they need fresh data but can tolerate a 60‑second stale window.
• Deployment must run on a Nitro‑compatible platform (Vercel, Netlify, Cloudflare Pages, or a custom Node server with persistent storage).

Smallest Suitable Design

The minimal architecture uses routeRules in nuxt.config.ts to map patterns to rendering modes. Nitro generates the appropriate server entry points or static assets at build time, so you avoid a custom Express layer.

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    // Nitro handles caching headers automatically when rules are set
  },
  routeRules: {
    // Static marketing home page
    '/': { prerender: true },
    // Static blog posts – generate all slugs at build time
    '/blog/**': { prerender: true },
    // Server‑side rendered admin area
    '/admin/**': { ssr: true },
    // Incremental Static Regeneration for hourly news updates
    '/news/**': { isr: 3600 },
    // Stale‑while‑revalidate for product catalog
    '/products/**': { swr: 60 }
  },
  runtimeConfig: {
    public: { apiBase: process.env.API_BASE },
    private: { dbPassword: process.env.DB_PASSWORD }
  }
});

Key points:

• prerender forces SSG at build time.
• ssr keeps the route on the server on every request.
• isr re‑generates the page in the background after the specified period.
• swr serves stale content while a background refresh runs.
• Runtime config is split into public (sent to the client) and private (only on the server).

Trust & Data Boundaries

Nuxt distinguishes between server‑only and client‑visible code:

1. SSR routes (e.g., /admin/**) can import db-client or fs because Nitro runs the handler in a Node environment.
2. SSG/ISR/SWR routes are built or executed at the edge. They must avoid importing server‑only modules. If a composable imports db-client, it will crash the build for static routes.
3. Use defineNuxtPlugin with mode: 'server' for logic that must stay server‑only, and mode: 'client' for client‑side only code.
4. When a route mixes SSR and SSG (e.g., a page that fetches user data on the client but renders a static header), guard the server import with a process.server check.

Operational Checks

After building and deploying, perform the following checks to confirm each rule’s behavior:

1. Local build verification
   • Run nuxi build.
   • Inspect .output/public for static HTML files. A file named index.html indicates prerender: true.
   • Check .output/server for _ssr.js entries – these are SSR handlers.
2. Deployment header inspection
   • Use curl -I https://example.com/blog/post-1 to confirm Cache-Control: public, max-age=0, s-maxage=31536000 for static pages.
   • For ISR pages, look for x-nitro-cache: stale or Cache-Control: stale-while-revalidate=60 headers.
   • For SWR pages, Cache-Control: stale-while-revalidate=60 should be present.
3. Runtime config audit
   • In a browser console, run console.log(useRuntimeConfig().public) – private keys must not appear.
   • Run npx @nuxt/test-utils run to mount the app and assert that useRuntimeConfig().private is undefined on the client.
4. Edge function validation
   • Deploy to Vercel and use vercel logs to ensure that edge‑only routes (e.g., /products/**) hit the edge runtime and not a Node server.
   • Check the build output for edge-functions directory.

Failure Modes & Mitigation

• ISR stampede: If many requests hit a page while it’s being regenerated, they can all trigger a rebuild. Mitigate by configuring swr: 60 on high‑traffic pages or by using Nitro’s revalidate: 'background' feature.
• Dynamic data at build time: A SSG route that calls $fetch to an API without a fallback will fail if the API is down. Use try/catch and provide a fallback component.
• Edge deployment breakage: Importing fs or net in a composable used by a SWR route will cause a build error. Audit composables with npx nuxi analyze.
• Middleware bypass on static pages: Auth middleware runs only on SSR or edge routes. For static pages that need client‑side auth, add a useRouteGuard composable that checks useAuth() on the client.

When the Design Changes

• Platform limits (e.g., Vercel’s 1000 static pages) force you to switch from prerender to isr or swr.
• If personalization grows, more routes may need ssr: true with a caching layer (e.g., Cloudflare Workers KV) to avoid per‑request database hits.
• Adopting micro‑frontends could push route handling to a gateway; in that case routeRules become per‑service rather than per‑page.
• Adding real‑time features (WebSockets) would require moving those routes out of Nitro’s static/edge context into a dedicated Node server.

Practical Checklist

Check	How to Verify	Expected Result
Static page generated	Inspect .output/public/index.html	Exists and contains full HTML
SSR handler present	Look for _ssr.js in .output/server	File exists for /admin/**
ISR cache header	curl -I on /news/**	Cache-Control: stale-while-revalidate=60
SWR header	curl -I on /products/**	Cache-Control: stale-while-revalidate=60
Runtime config privacy	Console log useRuntimeConfig() on client	No private keys exposed

Conclusion

Nuxt 3’s routeRules provide a declarative, zero‑code‑change way to assign the right rendering strategy to each page. By respecting trust boundaries, verifying build output, and monitoring runtime headers, you can deliver fast, fresh, and secure content across a single codebase. Keep in mind the limits of your deployment platform and the potential for cache stampedes, and adjust your rules accordingly.