Nuxt routeRules: Assigning Rendering Modes Per Route Instead of Globally

The problem with one global rendering mode

Nuxt applications often start with a single rendering choice. Setting ssr: true in nuxt.config.ts renders every page on the server; setting ssr: false ships a pure client-side app. That global switch is convenient, but it forces a homepage, a blog archive, a user dashboard, and an API proxy into the same performance profile. The practical solution is routeRules, which lets you assign a rendering strategy to each route pattern individually. Instead of choosing one mode for the entire project, you can prerender static pages, cache semi-dynamic content, server-render private pages, and leave API routes client-only—all in the same build.

How routeRules work

routeRules is a top-level key in nuxt.config.ts. Its keys are route globs—patterns like /, /blog/**, or /dashboard/**. Its values are objects that declare a rendering behavior for Nitro, the server engine Nuxt uses to build and serve your application. Nitro reads these rules at build time for static generation and at request time for server responses.

The supported directives include prerender for build-time static HTML, swr for stale-while-revalidate caching, isr for incremental static regeneration, ssr to force server rendering, and ssr: false to mark a route as client-only. You can also attach cache options where the runtime supports them.

A worked configuration for mixed rendering

The following nuxt.config.ts excerpt shows a typical hybrid setup:

export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },
    '/blog/**': { swr: true },
    '/dashboard/**': { ssr: true },
    '/api/**': { ssr: false }
  }
})

Each entry solves a different problem:

• /: The homepage is prerendered at build time. Nitro emits a static HTML file, so the first byte arrives quickly without waiting for a server render.
• /blog/**: Blog posts use SWR. The first request renders on the server and caches the result. Subsequent requests serve the cached HTML immediately while the server revalidates in the background.
• /dashboard/**: User dashboards are server-rendered on every request because they contain private, request-specific data.
• /api/**: API proxy routes are marked ssr: false. The page shell is not rendered on the server; the browser fetches data client-side.

This configuration keeps one codebase while giving each section the appropriate freshness and performance characteristics.

Route matching order and specificity

Nuxt evaluates routeRules and applies the most specific match. If two patterns overlap, the narrower pattern should take precedence. A common mistake is defining a broad catch-all such as '/:slug*' before a specific override like '/blog/featured'. Depending on the glob implementation, the broad rule can shadow the specific one, leaving the override silently ignored.

To avoid this, order your rules from most specific to least specific:

routeRules: {
  '/blog/featured': { prerender: true },
  '/blog/**': { swr: true },
  '/:slug*': { ssr: true }
}

Here, /blog/featured is prerendered, other blog routes use SWR, and everything else falls back to SSR. The exact matching algorithm may vary by Nuxt version, so verify the behavior in your project rather than assuming a particular precedence rule.

Limits you cannot ignore

SWR and ISR require a server runtime. They do not function when you export a fully static site with nuxi generate. If your deployment target is a static host with no server process, swr: true and isr have no effect. You need a Node server or an edge-compatible preset for these strategies to work.

Prerendering cannot include request-specific data. A prerendered route is generated once at build time. It cannot read cookies, authorization headers, or any other per-request information. If a page needs to show different content for different users, use SSR or a server route instead of prerender.

Deployment presets change behavior. A rule that works on a Node server may be ignored or altered when you deploy to a static or edge target. Nitro adapts the output to the preset, and caching semantics are not identical across platforms. Always test against the environment you will actually ship to.

Cache invalidation is host-dependent. SWR and ISR rely on HTTP caching headers, but how those headers are honored—and how stale content is purged—depends on your host or CDN. Local development behavior may not match production.

Common mistakes

Overlapping globs. As shown above, a broad pattern can shadow a specific override. Review your rules for conflicts before building.

Assuming client-side navigation bypasses the rules. When a user clicks a link inside your Nuxt app, the browser performs a client-side navigation and does not re-download the HTML shell. The rendering rule governs the initial document request, not subsequent in-app navigations. If you need different data on the client, handle that in your composables or plugins.

Expecting cache headers on static hosts. If you prerender your entire site and deploy the output folder to a static host, SWR and ISR headers will not appear because there is no server to attach them. The files are simply static assets.

Verifying the result

After configuring routeRules, run the build from your project root:

npx nuxi build

This command requires Node.js and your project dependencies to be installed. It writes generated assets and server bundles into your output directory. Inspect that directory: prerendered routes should emit HTML files, while dynamic routes should appear in the server bundle. If a route you expected to be prerendered is missing from the static output, check for overlapping globs or preset incompatibilities.

For SWR or ISR, deploy to your target preset and inspect the HTTP response headers—specifically cache-control—to confirm the caching strategy is active. You can also check Nitro build logs or run npx nuxi analyze to see which routes were treated as static versus server-rendered.

A practical final check is to open a prerendered route in a browser with JavaScript disabled. If the content is visible, the prerender succeeded. For an SSR route, confirm that the server bundle contains the route handler and that private data is not leaking into static output.

Version assumptions

This guidance targets Nuxt 3 with Nitro. Glob syntax, cache directives, and preset behavior can shift between minor releases. If you are on an older or newer version, confirm the exact routeRules options in your installed nuxt package before relying on them in production.