What hybrid rendering with ESR enables
Hybrid rendering can be used when using Edge-Side Rendering with route rules. This allows you to combine different caching rules and rendering modes with the performance benefits of edge server rendering.
rendering-modes
82 notes in this subject, read out of this brain and free to use. This is page 2 of 2.
ESR powered by Nitro
Edge-side rendering is possible thanks to Nitro, the server engine that powers Nuxt. Nitro offers cross-platform support for Node.js, Deno, Cloudflare Workers, and more.
ESR deployment platforms
The current platforms where you can leverage Edge-Side Rendering are: Cloudflare Pages (with zero configuration using git integration and `nuxt build`), Vercel Cloud (using `nuxt build` and `NITRO_PRESET=vercel-edge` environment variable), and Netlify Edge Functions (using `nuxt build` and `NITRO_PRESET=netlify-edge` environment variable).
Server components (island components) definition
Server components, also called island components, are rendered on the server with their HTML embedded in the page and no JavaScript sent to the client. Their dependencies stay on the server. This is useful for content-heavy components like markdown rendering, syntax highlighting, or CMS output that never change on the client.
Server components enabled via experimental.componentIslands
Server components are controlled by the experimental.componentIslands configuration option. The default value is 'auto', which enables the feature automatically when your app contains a server component or island.
Server component configuration options
The experimental.componentIslands option accepts two properties: selectiveClient (boolean or 'deep' to enable nuxt-client for selective hydration) and remoteIsland (boolean to allow rendering islands from a remote source).
Pairing .server.vue with .client.vue components
A .server.vue component can be paired with a .client.vue component of the same name to provide separate server and client implementations. When paired this way, the component is not an island and the client half hydrates normally.
Server components must have a single root element
Server components and islands must have a single root element. HTML comments are considered elements as well.
How islands are rendered with NuxtIsland
Server components use <NuxtIsland> under the hood. Rendering an island issues a request to a dedicated island endpoint which creates a new, isolated Vue app on the server to render just that component, creates an 'island context' accessible via nuxtApp.ssrContext.islandContext, and runs plugins again unless they set env: { islands: false }.
Islands are isolated from main app state
Because islands are isolated, you cannot share state (provide/inject, Pinia, useState) between the page and the island. Pass data via props instead. useRoute() inside an island reflects the island's own request, not the page the user is on. Route middleware does not run when rendering islands.
Island props serialization via GET query parameters
Props are serialized and sent as GET query parameters in island rendering. This makes island responses cacheable but means props must be JSON-serializable, are limited by URL length, and may be visible in server access logs, CDN caches and Referer headers.
Treating island props as untrusted input
Because props come from the request URL query or body, treat them as untrusted input. Nuxt rejects a top-level 'as' prop that the island does not declare and, with vue.runtimeCompiler enabled, a 'template' prop. Avoid feeding props into dynamic component resolution without validation, and set defineOptions({ inheritAttrs: false }) on islands whose root is polymorphic.
Changing island props triggers re-render
Changing an island's props triggers a network request that re-renders the component on the server and updates its HTML in place.
Selective hydration with nuxt-client attribute
You can hydrate individual components inside a server island by adding the nuxt-client attribute. This requires experimental.componentIslands.selectiveClient to be enabled. The component marked with nuxt-client is server-rendered as part of the island, then hydrated by the main client app, with only its chunk shipped to the client.
Deep selective client hydration with selectiveClient: 'deep'
Setting selectiveClient: 'deep' additionally allows passing slots to nuxt-client components. Those slots are rendered on the server and are not interactive on the client.
nuxt-client attribute limitations
Use nuxt-client only on local .vue SFCs. Built-ins like <NuxtLink> skip the islands transform. After client navigation you may see 'Failed to locate Teleport target' or the link disappears. Wrap the built-in in your own .vue file and put nuxt-client on that wrapper.
Island slots are interactive when declared
Slots can be passed to an island component if declared in the island. Slot content is provided by the parent, belongs to the main client app, and is interactive (wrapped in a div with display: contents;). <NuxtIsland> reserves the #fallback slot for content rendered before the island loads or when fetching fails.
Client-side navigation with islands requires network requests
On initial server-rendered page load, islands are rendered inline with no extra request. On client-side navigation, however, each island on the destination page must be fetched from the server. Islands block on a network round trip during navigation unless you pass the lazy prop with a #fallback slot. Use the lazy prop to render islands non-blockingly.
Islands work best for pages with full page loads
Islands work best on pages reached by full page loads (content and marketing pages) or when their number per page is small. If a component needs to update frequently on the client, an island is probably the wrong tool.
Island caching with prerendering
During prerendering (nuxt generate or prerender route rules), island responses are cached, so identical islands (same name, props and context) are rendered once and reused. Because props travel as GET query parameters, island responses can be cached by your server or CDN at the island endpoint level.
Islands with noScripts route rule limitation
Island slots and nuxt-client components rely on a small inline script to relocate teleported content before hydration. On routes rendered with noScripts, that script is omitted, so fully interactive nuxt-client components will not hydrate there. Plain static islands are unaffected.
Server components current limitations
Server components are experimental with several limitations: most features are only available for single file components; global styles are sent with each island response and island assets can be loaded twice; islands can significantly increase chunk count at build time; with webpack/Rspack, scoped :slotted() styles can fail; template refs cannot reference elements inside a server component from parent; inject/provide does not cross island boundary; auto-generated wrapper components do not expose load and error events; useId has known limitations inside islands; nested islands add extra overhead.