Deep Dive: How Nuxt 4.0’s Hybrid Rendering Works with Vue 3.5 and Nitro 2.9

Hybrid rendering has become a cornerstone of modern full-stack frameworks, letting developers mix server-side rendering (SSR), static site generation (SSG), and client-side rendering (CSR) per route. Nuxt 4.0 takes this further by aligning deeply with Vue 3.5’s performance upgrades and Nitro 2.9’s flexible server engine. This guide breaks down the internals of Nuxt 4.0’s hybrid rendering, its integration points with Vue 3.5 and Nitro 2.9, and practical configuration examples.

What Is Hybrid Rendering in Nuxt 4.0?

Unlike earlier Nuxt versions that required global rendering mode choices, Nuxt 4.0 lets you define rendering behavior per route or per route group using the routeRules config. Supported modes include:

SSR: Server-renders every request, ideal for dynamic, personalized content.
SSG: Pre-renders pages at build time, perfect for static marketing pages or blogs.
Hybrid: Mixes SSR for dynamic routes and SSG for static ones, with optional incremental static regeneration (ISR) to update pre-rendered pages without full rebuilds.
CSR: Pure client-side rendering, useful for authenticated dashboards or highly interactive app sections.

Nuxt 4.0’s hybrid rendering is powered by two core dependencies: Vue 3.5 for client-side reactivity and component rendering, and Nitro 2.9 for server-side logic, build output, and deployment flexibility.

Vue 3.5: The Client-Side Foundation

Vue 3.5 (released alongside Nuxt 4.0) brings critical performance and DX improvements that enhance hybrid rendering workflows:

Reactivity Transform v2: Simplified reactive state management with $() and $ref macros, reducing boilerplate for hybrid components that run on both server and client.
Improved Hydration Mismatch Handling: Vue 3.5 detects and recovers from hydration mismatches more gracefully, reducing runtime errors when SSR output differs from client-side expectations.
Smaller Bundle Size: Tree-shaking improvements cut Vue’s baseline bundle size by 12% compared to Vue 3.4, speeding up client-side hydration for hybrid pages.
Enhanced Teleport and Suspense: Better support for async components and portal-based UI in hybrid rendering scenarios, where parts of a page may be SSR’d and others CSR’d.

When Nuxt 4.0 server-renders a page, it uses Vue 3.5’s server-side rendering API to generate the initial HTML, then hydrates the client-side with the same Vue 3.5 build, ensuring consistent behavior across environments.

Nitro 2.9: The Server Engine Powering Hybrid Rendering

Nitro 2.9 is the underlying server toolkit for Nuxt 4.0, handling build, dev server, and production deployment. For hybrid rendering, Nitro 2.9 adds three key capabilities:

Per-Route Rule Evaluation: Nitro 2.9 processes routeRules at request time (for SSR) and build time (for SSG), letting you override rendering modes, cache headers, and proxy rules per route without restarting the server.
Edge-Ready Output: Nitro 2.9 can compile hybrid Nuxt apps to edge-compatible bundles (Cloudflare Workers, Vercel Edge, AWS Lambda@Edge), with built-in support for edge-side rendering and ISR.
Unified Build Pipeline: Nitro 2.9 merges Vue 3.5 client builds, server-side rendering logic, and static pre-rendered pages into a single output directory, simplifying deployment for hybrid apps.

Nitro 2.9 also introduces a new hybrid preset that automatically configures cache rules, serverless function splitting, and static asset serving for mixed rendering workloads.

Configuring Hybrid Rendering in Nuxt 4.0

To enable hybrid rendering, update your nuxt.config.ts with routeRules. Below is a sample config that mixes SSG, SSR, and ISR:

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    routeRules: {
      // Static blog posts: pre-render at build time, revalidate every 60 seconds (ISR)
      '/blog/**': { prerender: true, isr: 60 },
      // Dynamic user dashboard: SSR every request, no caching
      '/dashboard/**': { ssr: true, cache: false },
      // Marketing pages: pure SSG, never revalidate
      '/about': { prerender: true },
      // App shell: CSR only, load entirely on client
      '/app/**': { csr: true, ssr: false }
    }
  },
  // Enable Vue 3.5 reactivity transforms (optional)
  vue: {
    reactivityTransform: true
  }
})

This config tells Nitro 2.9 to pre-render blog posts with ISR, SSR dashboard pages on every request, statically generate the about page, and render app routes entirely on the client. Vue 3.5 handles hydration for all SSR/ISR pages, while CSR routes skip server rendering entirely.

How Hybrid Rendering Works Under the Hood

When a request hits a Nuxt 4.0 hybrid app, the flow is:

Nitro 2.9 checks routeRules for the requested path to determine rendering mode.
If SSG/ISR: Nitro serves the pre-rendered HTML from the build output, or revalidates the page if the ISR TTL has expired.
If SSR: Nitro invokes Vue 3.5’s SSR renderer to generate HTML from the component tree, injects initial state, and returns the response.
If CSR: Nitro serves a minimal HTML shell with the Vue 3.5 client bundle, which takes over rendering on the client.
For all non-CSR pages: The Vue 3.5 client bundle hydrates the server-rendered HTML, attaching event listeners and reactivity without re-rendering the entire page.

Nuxt 4.0 also shares state between server and client via the useState composable, which is serialized to the HTML response during SSR and rehydrated by Vue 3.5 on the client, ensuring consistency across rendering modes.

Performance Benefits of the Nuxt 4.0 + Vue 3.5 + Nitro 2.9 Stack

Combining these tools delivers measurable performance gains:

30% faster SSR response times compared to Nuxt 3, thanks to Nitro 2.9’s optimized server pipeline and Vue 3.5’s faster SSR rendering.
20% smaller client bundles due to Vue 3.5’s tree-shaking and Nitro 2.9’s code splitting for hybrid routes.
Reduced time-to-interactive (TTI) for hybrid pages, as Vue 3.5’s improved hydration skips re-rendering unchanged DOM nodes.

Conclusion

Nuxt 4.0’s hybrid rendering is a tightly integrated system that leverages Vue 3.5’s client-side capabilities and Nitro 2.9’s server flexibility to let developers choose the right rendering mode for every route. Whether you’re building a static blog, a dynamic e-commerce site, or a hybrid app, this stack delivers better performance, simpler configuration, and broader deployment options than ever before. Try out the sample config above to start experimenting with hybrid rendering in your Nuxt 4.0 projects.

推荐订阅源

DEV Community