mirror of
https://github.com/nuxt/nuxt.git
synced 2024-12-12 23:37:14 +00:00
234 lines
16 KiB
Markdown
234 lines
16 KiB
Markdown
---
|
|
title: 'Rendering Modes'
|
|
description: 'Learn about the different rendering modes available in Nuxt.'
|
|
---
|
|
|
|
Nuxt supports different rendering modes, [universal rendering](#universal-rendering), [client-side rendering](#client-side-rendering) but also offers [hybrid-rendering](#hybrid-rendering) and the possibility to render your application on [CDN Edge Servers](#edge-side-rendering).
|
|
|
|
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](/docs/api/nuxt-config#ssr).
|
|
|
|
## 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.
|
|
|
|
```vue [app.vue]
|
|
<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](/docs/guide/directory-structure/middleware) and [pages](/docs/guide/directory-structure/pages) run in the server and on the client during hydration. [Plugins](/docs/guide/directory-structure/plugins) can be rendered on the server or client or both. [Components](/docs/guide/directory-structure/components) can be forced to run on the client only as well. [Composables](/docs/guide/directory-structure/composables) and [utilities](/docs/guide/directory-structure/utils) 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](#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.**
|
|
|
|
::tip
|
|
For more examples about writing Vue code without hydration mismatch, see [the Vue docs](https://vuejs.org/guide/scaling-up/ssr.html#hydration-mismatch).
|
|
::
|
|
|
|
::important
|
|
When importing a library that relies on browser APIs and has side effects, make sure the component importing it is only called client-side. Bundlers do not treeshake imports of modules containing side effects.
|
|
::
|
|
|
|
## 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`:
|
|
|
|
```ts [nuxt.config.ts]
|
|
export default defineNuxtConfig({
|
|
ssr: false
|
|
})
|
|
```
|
|
|
|
::note
|
|
If you do use `ssr: false`, you should also place an HTML file in `~/app/spa-loading-template.html` with some HTML you would like to use to render a loading screen that will be rendered until your app is hydrated.
|
|
:read-more{title="SPA Loading Template" to="/docs/api/configuration/nuxt-config#spaloadingtemplate"}
|
|
::
|
|
|
|
::tip{to="https://www.youtube.com/watch?v=7Lr0QTP1Ro8" icon="i-logos-youtube-icon" target="_blank"}
|
|
Watch a video from Alexander Lichter about **Building a plain SPA with Nuxt!?**.
|
|
::
|
|
|
|
### Deploying a Static Client-Rendered App
|
|
|
|
If you deploy your app to [static hosting](/docs/getting-started/deployment#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](/docs/api/advanced/hooks#nuxt-hooks-build-time) in your `nuxt.config.ts`:
|
|
|
|
```ts twoslash [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](https://nitro.unjs.io/guide/cache).
|
|
|
|
```ts twoslash [nuxt.config.ts]
|
|
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`{lang=ts} - Define server-side redirects.
|
|
- `ssr: boolean`{lang=ts} - 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`{lang=ts} - Automatically adds cors headers with `cors: true` - you can customize the output by overriding with `headers`
|
|
- `headers: object`{lang=ts} - Add specific headers to sections of your site - for example, your assets
|
|
- `swr: number | boolean`{lang=ts} - 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`{lang=ts} - 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`{lang=ts} - Prerenders routes at build time and includes them in your build as static assets
|
|
- `experimentalNoScripts: boolean`{lang=ts} - Disables rendering of Nuxt scripts and JS resource hints for sections of your site.
|
|
- `appMiddleware: string | string[] | Record<string, boolean>`{lang=ts} - 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).
|
|
|
|
::important
|
|
Note that Hybrid Rendering is not available when using [`nuxt generate`](/docs/api/commands/generate).
|
|
::
|
|
|
|
**Examples:**
|
|
|
|
::card-group
|
|
::card
|
|
---
|
|
icon: i-simple-icons-github
|
|
title: Nuxt Vercel ISR
|
|
to: https://github.com/danielroe/nuxt-vercel-isr
|
|
target: _blank
|
|
ui.icon.base: text-black dark:text-white
|
|
---
|
|
Example of a Nuxt application with hybrid rendering deployed on Vercel.
|
|
::
|
|
::
|
|
|
|
## 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](https://nitro.unjs.io), the [server engine](/docs/guide/concepts/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](https://pages.cloudflare.com) with zero configuration using the git integration and the `nuxt build` command
|
|
- [Vercel Edge Functions](https://vercel.com/features/edge-functions) using the `nuxt build` command and `NITRO_PRESET=vercel-edge` environment variable
|
|
- [Netlify Edge Functions](https://www.netlify.com/products/#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:
|
|
::card-group
|
|
::card
|
|
---
|
|
icon: i-simple-icons-github
|
|
title: Nuxt Todos Edge
|
|
to: https://github.com/atinux/nuxt-todos-edge
|
|
target: _blank
|
|
ui.icon.base: text-black dark:text-white
|
|
---
|
|
A todos application with user authentication, SSR and SQLite.
|
|
::
|
|
::card
|
|
---
|
|
icon: i-simple-icons-github
|
|
title: Atinotes
|
|
to: https://github.com/atinux/atinotes
|
|
target: _blank
|
|
ui.icon.base: text-black dark:text-white
|
|
---
|
|
An editable website with universal rendering based on Cloudflare KV.
|
|
::
|
|
::
|
|
|
|
<!-- TODO: link to templates with ESR category for examples -->
|