components/islands

19 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Server Components (Island Components) definition

Server components, also called island components, are rendered on the server and their HTML is embedded in the page. None of their JavaScript is sent to the client, and 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.

experimental.componentIslands configuration

Component islands are controlled by the experimental.componentIslands configuration option. The default value is 'auto', which enables the feature automatically as soon as the app contains a server component or island. To explicitly enable features, set it to an object with properties: selectiveClient (boolean or 'deep' to enable nuxt-client), and remoteIsland (boolean to allow rendering islands from a remote source).

.server.vue component file naming

Add the .server suffix to a component filename to make it a standalone server component. For example, HighlightedMarkdown.server.vue. Components inside ~/components/islands/ are also automatically registered as islands.

.server.vue and .client.vue paired components

A .server.vue component can be paired with a .client.vue component of the same name for separate server and client implementations. In that case, the component is not an island; the client half hydrates normally.

Server components single root element requirement

Server components and islands must have a single root element. HTML comments are considered elements as well.

Island rendering mechanism and isolation

Server components use <NuxtIsland> under the hood. Rendering an island creates a new, isolated Vue app on the server to render just that component. It creates an 'island context' accessible via nuxtApp.ssrContext.islandContext inside the island and runs plugins again unless they set env: { islands: false }. Because islands are isolated: state cannot be shared between the page and island (use 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 and constraints

Island props are serialized and sent as GET query parameters, making island responses cacheable. This means props must be JSON-serializable, are limited by URL length so avoid passing large amounts of data, and may be visible in server access logs, CDN caches and Referer headers. Props are treated as untrusted input; Nuxt rejects top-level 'as' that the island does not declare and, with vue.runtimeCompiler enabled, a 'template' anywhere in the props.

Island props security: dynamic component resolution

Avoid feeding props you have not validated into dynamic component resolution (<component :is>, h(), resolveDynamicComponent(), or a polymorphic as / asChild prop), since a string can resolve to any registered component or HTML element. To switch components based on caller input, map a discriminator through an allowlist of imported components rather than passing the raw prop.

Island props fallthrough as attributes

Props a component does not declare fall through as attributes onto its single root element. An island whose root is a polymorphic component can receive attributes you did not bind. Set defineOptions({ inheritAttrs: false }) on such islands, or declare the props you accept.

Island props change 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.

nuxt-client attribute for selective hydration

An island is static by default, but you can hydrate individual components inside it 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. Only its chunk is shipped to the client; the rest of the island remains static.

selectiveClient: 'deep' for slots on nuxt-client components

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 limitation with built-in components

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 with no error. Wrap the built-in in your own .vue file and put nuxt-client on that wrapper.

Island slots behavior

Slots can be passed to an island component if declared in the island. Slot content is provided by the parent, so it belongs to the main client app and is interactive (wrapped in a <div> with display: contents;). <NuxtIsland> reserves the #fallback slot to specify content rendered before the island loads (when lazy is set) or when fetching the island fails.

Client-side navigation and island requests

On initial server-rendered page load, islands are rendered inline with no extra request. On client-side navigation, 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) to render them non-blockingly. Apps with many islands per page make many requests per navigation. Islands work best on pages reached by full page loads or when their number per page is small.

Island prerendering and caching behavior

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. Two instances of the same island with the same props share a single server render and payload entry.

Island caching independence from page context

Island responses are keyed only on name, props and context, which keeps them cacheable independently of the page they appear on. This is why they cannot see the current route.

Island slots and nuxt-client with noScripts route rules

Island slots and nuxt-client components rely on a small inline script to relocate teleported content into place 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 limitations

Most features for server-only and island components are only available for single file components. Global styles of the application are sent with each island response, and island assets can be loaded twice in some setups. Using islands can significantly increase the number of chunks generated at build time. :slotted() styles are ignored in server component slots. Template refs cannot reference elements inside a server component from the parent. inject/provide does not cross the island boundary. Server components rendered via auto-generated wrapper do not expose load and error events; use <NuxtIsland> directly if you need its error event and refresh() method. useId has known limitations inside islands. Each nested island adds extra overhead.

Give your agent this brain