Rendering Modes

Nuxt supports different rendering modes, universal rendering, client-side rendering but also offers hybrid-rendering and the possibility to render your application on CDN Edge Servers.

Both the browser and server can interpret JavaScript code to turn Vue.js components into HTML elements. This step is called rendering. Nuxt supports both universal and client-side rendering. The two approaches have benefits and downsides that we will cover.

By default, Nuxt uses universal rendering to provide better user experience, performance and to optimize search engine indexing, but you can switch rendering modes in one line of configuration.

Universal Rendering

This step is similar to traditional server-side rendering performed by PHP or Ruby applications. When the browser requests a URL with universal rendering enabled, Nuxt runs the JavaScript (Vue.js) code in a server environment and returns a fully rendered HTML page to the browser. Nuxt may also return a fully rendered HTML page from a cache if the page was generated in advance. Users immediately get the entirety of the initial content of the application, contrary to client-side rendering.

Once the HTML document has been downloaded, the browser interprets this and Vue.js takes control of the document. The same JavaScript code that once ran on the server runs on the client (browser) again in the background now enabling interactivity (hence Universal rendering) by binding its listeners to the HTML. This is called Hydration. When hydration is complete, the page can enjoy benefits such as dynamic interfaces and page transitions.

Universal rendering allows a Nuxt application to provide quick page load times while preserving the benefits of client-side rendering. Furthermore, as the content is already present in the HTML document, crawlers can index it without overhead.

What's server-rendered and what's client-rendered?

It is normal to ask which parts of a Vue file runs on the server and/or the client in universal rendering mode.

<script setup lang="ts">
const counter = ref(0); // executes in server and client environments

const handleClick = () => {
  counter.value++; // executes only in a client environment
};
</script>

<template>
  <div>
    <p>Count: {{ counter }}</p>
    <button @click="handleClick">Increment</button>
  </div>
</template>

On the initial request, the counter ref is initialized in the server since it is rendered inside the <p> tag. The contents of handleClick is never executed here. During hydration in the browser, the counter ref is re-initialized. The handleClick finally binds itself to the button; Therefore it is reasonable to deduce that the body of handleClick will always run in a browser environment.

Middlewares and pages run in the server and on the client during hydration. Plugins can be rendered on the server or client or both. Components can be forced to run on the client only as well. Composables and utilities are rendered based on the context of their usage.

Benefits of server-side rendering:

• Performance: Users can get immediate access to the page's content because browsers can display static content much faster than JavaScript-generated content. At the same time, Nuxt preserves the interactivity of a web application during the hydration process.
• Search Engine Optimization: Universal rendering delivers the entire HTML content of the page to the browser as a classic server application. Web crawlers can directly index the page's content, which makes Universal rendering a great choice for any content that you want to index quickly.

Downsides of server-side rendering:

• Development constraints: Server and browser environments don't provide the same APIs, and it can be tricky to write code that can run on both sides seamlessly. Fortunately, Nuxt provides guidelines and specific variables to help you determine where a piece of code is executed.
• Cost: A server needs to be running in order to render pages on the fly. This adds a monthly cost like any traditional server. However, the server calls are highly reduced thanks to universal rendering with the browser taking over on client-side navigation. A cost reduction is possible by leveraging edge-side-rendering.

Universal rendering is very versatile and can fit almost any use case, and is especially appropriate for any content-oriented websites: blogs, marketing websites, portfolios, e-commerce sites, and marketplaces.

Client-Side Rendering

Out of the box, a traditional Vue.js application is rendered in the browser (or client). Then, Vue.js generates HTML elements after the browser downloads and parses all the JavaScript code containing the instructions to create the current interface.

Benefits of client-side rendering:

• Development speed: When working entirely on the client-side, we don't have to worry about the server compatibility of the code, for example, by using browser-only APIs like the window object.
• Cheaper: Running a server adds a cost of infrastructure as you would need to run on a platform that supports JavaScript. We can host Client-only applications on any static server with HTML, CSS, and JavaScript files.
• Offline: Because code entirely runs in the browser, it can nicely keep working while the internet is unavailable.

Downsides of client-side rendering:

• Performance: The user has to wait for the browser to download, parse and run JavaScript files. Depending on the network for the download part and the user's device for the parsing and execution, this can take some time and impact the user's experience.
• Search Engine Optimization: Indexing and updating the content delivered via client-side rendering takes more time than with a server-rendered HTML document. This is related to the performance drawback we discussed, as search engine crawlers won't wait for the interface to be fully rendered on their first try to index the page. Your content will take more time to show and update in search results pages with pure client-side rendering.

Client-side rendering is a good choice for heavily interactive web applications that don't need indexing or whose users visit frequently. It can leverage browser caching to skip the download phase on subsequent visits, such as SaaS, back-office applications, or online games.

You can enable client-side only rendering with Nuxt in your nuxt.config.ts:

export default defineNuxtConfig({
  ssr: false
})

Deploying a Static Client-Rendered App

If you deploy your app to static hosting with the nuxi generate or nuxi build --prerender commands, then by default, Nuxt will render every page as a separate static HTML file.

If you are using purely client-side rendering, then this might be unnecessary. You might only need a single index.html file, plus 200.html and 404.html fallbacks, which you can tell your static web host to serve up for all requests.

In order to achieve this we can change how the routes are prerendered. Just add this to your hooks in your nuxt.config.ts:

export default 
defineNuxtConfig
({
  
hooks
: {
    'prerender:routes' ({ 
routes
 }) {
      
routes
.
clear
() // Do not generate any routes (except the defaults)
    }
  },
})

This will produce three files:

• index.html
• 200.html
• 404.html

The 200.html and 404.html might be useful for the hosting provider you are using.

Hybrid Rendering

Hybrid rendering allows different caching rules per route using Route Rules and decides how the server should respond to a new request on a given URL.

Previously every route/page of a Nuxt application and server must use the same rendering mode, universal or client-side. In various cases, some pages could be generated at build time, while others should be client-side rendered. For example, think of a content website with an admin section. Every content page should be primarily static and generated once, but the admin section requires registration and behaves more like a dynamic application.

Nuxt includes route rules and hybrid rendering support. Using route rules you can define rules for a group of nuxt routes, change rendering mode or assign a cache strategy based on route!

Nuxt server will automatically register corresponding middleware and wrap routes with cache handlers using Nitro caching layer.

export default 
defineNuxtConfig
({
  
routeRules
: {
    // Homepage pre-rendered at build time
    '/': { 
prerender
: true },
    // Products page generated on demand, revalidates in background, cached until API response changes
    '/products': { 
swr
: true },
    // Product pages generated on demand, revalidates in background, cached for 1 hour (3600 seconds)
    '/products/**': { 
swr
: 3600 },
    // Blog posts page generated on demand, revalidates in background, cached on CDN for 1 hour (3600 seconds)
    '/blog': { 
isr
: 3600 },
    // Blog post page generated on demand once until next deployment, cached on CDN
    '/blog/**': { 
isr
: true },
    // Admin dashboard renders only on client-side
    '/admin/**': { 
ssr
: false },
    // Add cors headers on API routes
    '/api/**': { 
cors
: true },
    // Redirects legacy urls
    '/old-page': { 
redirect
: '/new-page' }
  }
})

Route Rules

The different properties you can use are the following:

• redirect: string - Define server-side redirects.
• ssr: boolean - Disables server-side rendering of the HTML for sections of your app and make them render only in the browser with ssr: false
• cors: boolean - Automatically adds cors headers with cors: true - you can customize the output by overriding with headers
• headers: object - Add specific headers to sections of your site - for example, your assets
• swr: number | boolean - Add cache headers to the server response and cache it on the server or reverse proxy for a configurable TTL (time to live). The node-server preset of Nitro is able to cache the full response. When the TTL expired, the cached response will be sent while the page will be regenerated in the background. If true is used, a stale-while-revalidate header is added without a MaxAge.
• isr: number | boolean - The behavior is the same as swr except that we are able to add the response to the CDN cache on platforms that support this (currently Netlify or Vercel). If true is used, the content persists until the next deploy inside the CDN.
• prerender: boolean - Prerenders routes at build time and includes them in your build as static assets
• experimentalNoScripts: boolean - Disables rendering of Nuxt scripts and JS resource hints for sections of your site.
• appMiddleware: string | string[] | Record<string, boolean> - Allows you to define middleware that should or should not run for page paths within the Vue app part of your application (that is, not your Nitro routes)

Whenever possible, route rules will be automatically applied to the deployment platform's native rules for optimal performances (Netlify and Vercel are currently supported).

Examples:

Edge-Side Rendering

Edge-Side Rendering (ESR) is a powerful feature introduced in Nuxt that allows the rendering of your Nuxt application closer to your users via edge servers of a Content Delivery Network (CDN). By leveraging ESR, you can ensure improved performance and reduced latency, thereby providing an enhanced user experience.

With ESR, the rendering process is pushed to the 'edge' of the network - the CDN's edge servers. Note that ESR is more a deployment target than an actual rendering mode.

When a request for a page is made, instead of going all the way to the original server, it's intercepted by the nearest edge server. This server generates the HTML for the page and sends it back to the user. This process minimizes the physical distance the data has to travel, reducing latency and loading the page faster.

Edge-side rendering is possible thanks to Nitro, the server engine that powers Nuxt 3. It offers cross-platform support for Node.js, Deno, Cloudflare Workers, and more.

The current platforms where you can leverage ESR are:

• Cloudflare Pages with zero configuration using the git integration and the nuxt build command
• Vercel Edge Functions using the nuxt build command and NITRO_PRESET=vercel-edge environment variable
• Netlify Edge Functions using the nuxt build command and NITRO_PRESET=netlify-edge environment variable

Note that Hybrid Rendering can be used when using Edge-Side Rendering with route rules.

You can explore open source examples deployed on some of the platform mentioned above: