Fine‑tuning performance: using Nuxt 3 route rules to mix SSR, SSG, ISR and SPA

Problem

When a site needs some pages to be fully server‑rendered for SEO, others to be statically generated for speed, and a dashboard to stay interactive, building separate Nuxt apps or manually switching modes becomes cumbersome.

Thesis

Nuxt 3’s route rules let you declare the rendering strategy for each URL pattern directly in nuxt.config.ts. One configuration file can mix SSR, SSG, ISR and SPA, delivering the right trade‑off per page without extra builds.

What route rules are

A route rule maps a URL pattern (exact, wildcard or regex) to a rendering mode:

• ssr – server‑side rendered on each request (default).
• static – pre‑rendered at build time with nuxi generate.
• swr – stale‑while‑revalidate; a cached HTML page is served and revalidated on edge functions.
• isr – incremental static regeneration; the page is regenerated on demand after a TTL.
• spa – client‑only hydration, no server rendering.

Defining the rules

Open nuxt.config.ts in your project root and add a routeRules object. Example:

export default defineNuxtConfig({
  routeRules: {
    '/marketing*': { static: true },               // pre‑rendered at build
    '/blog/**': { swr: 60 },                    // cache 60 seconds, revalidate on edge
    '/dashboard': { spa: true },                  // client‑only, no SSR
    '/api/**': { ssr: true, headers: { 'Cache-Control': 'public, max-age=0' } }
  }
})

Run the commands below in the project directory (you need write access to nuxt.config.ts and Node ≥ 18):

1. npm run build – compiles the app and generates the Nitro server.
2. npm run generate – executes nuxi generate to pre‑render static routes, respecting the static and swr rules.
3. Inspect .output to see which routes have HTML files (static) and which are delegated to Nitro (SSR/ISR).

Risks: overlapping patterns (e.g., /blog/* and /blog/posts/*) may cause the more specific rule to be ignored; mis‑typed keys break TypeScript inference, so add a nuxt.d.ts augmentation if you use dynamic parameters.

Verification

To confirm the rules work, follow these steps:

1. Create a fresh project: npx nuxi@latest init test-hybrid && cd test-hybrid.
2. Add the rule snippet above to nuxt.config.ts.
3. Run npm run build then npm run generate. After completion, list .output:

ls -R .output

You should see a folder static/blog/** for the blog pages and a server directory for the dashboard and API.

4. Deploy to a platform that supports edge functions (Vercel, Netlify, Cloudflare Pages). For a test route, add swr: 60 to /blog/post-1.
5. Visit the page, wait more than 60 seconds, then request it again. In the network tab look for the header x-nuxt-revalidated (Vercel) or x-nitro-revalidate (Netlify); its presence confirms ISR is active.
6. Run npx nuxi typecheck to ensure TypeScript correctly infers the route‑rule keys and rendering literals.

If the expected headers are missing, double‑check that your deployment preset enables ISR (e.g., nitro: { preset: 'vercel' }) and that the route pattern matches exactly.

Trade‑offs and limitations

• ISR/SWR only work where Nitro can run edge functions; nuxi preview does not replicate real revalidation.
• Each additional rule adds to build time and bundle size; monitor npm run build -- --profile for regressions.
• Dynamic routes that need generate must list them in nuxi generate config; otherwise they return 404 at build time.
• Header names such as x-vercel-revalidate are abstracted but may differ per CDN; verify behavior on your target provider.

Actionable closing

Start by adding a single rule for a high‑traffic page, run npm run generate, and verify the output folder. Iterate, using nuxi typecheck to keep TypeScript happy, and monitor build logs for any unexpected mode assignments. With route rules you can fine‑tune SEO, speed and interactivity in one Nuxt 3 application.