From 09e53fc6d94fbc8c34bac723a2946817d5f80025 Mon Sep 17 00:00:00 2001 From: Julien Huang Date: Mon, 25 Mar 2024 11:27:20 +0100 Subject: [PATCH] docs: warn about single root element for server components (#26462) --- docs/2.guide/2.directory-structure/1.components.md | 4 ++++ docs/2.guide/2.directory-structure/1.pages.md | 6 +++++- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/2.guide/2.directory-structure/1.components.md b/docs/2.guide/2.directory-structure/1.components.md index a33a0cbff8..0685a3389c 100644 --- a/docs/2.guide/2.directory-structure/1.components.md +++ b/docs/2.guide/2.directory-structure/1.components.md @@ -299,6 +299,10 @@ Now you can register server-only components with the `.server` suffix and use th Server-only components use [``](/docs/api/components/nuxt-island) under the hood, meaning that `lazy` prop and `#fallback` slot are both passed down to it. +::alert{type=warning} +Server components (and islands) must have a single root element. (HTML comments are considered elements as well.) +:: + ::alert{type=warning} Most features for server-only components and island components, such as slots and client components, are only available for single file components. :: diff --git a/docs/2.guide/2.directory-structure/1.pages.md b/docs/2.guide/2.directory-structure/1.pages.md index bef7ad02d2..6ebd687bb1 100644 --- a/docs/2.guide/2.directory-structure/1.pages.md +++ b/docs/2.guide/2.directory-structure/1.pages.md @@ -57,7 +57,7 @@ If you are using [`app.vue`](/docs/guide/directory-structure/app), make sure to ``` -Pages **must have a single root element** to allow [route transitions](/docs/getting-started/transitions) between pages, HTML comments are considered elements as well. +Pages **must have a single root element** to allow [route transitions](/docs/getting-started/transitions) between pages. HTML comments are considered elements as well. This means that when the route is server-rendered, or statically generated, you will be able to see its contents correctly, but when you navigate towards that route during client-side navigation the transition between routes will fail and you'll see that the route will not be rendered. @@ -365,6 +365,10 @@ You can define a page as [client only](/docs/guide/directory-structure/component You can define a page as [server only](/docs/guide/directory-structure/components#server-components) by giving it a `.server.vue` suffix. While you will be able to navigate to the page using client-side navigation, controlled by `vue-router`, it will be rendered with a server component automatically, meaning the code required to render the page will not be in your client-side bundle. +::alert{type=warning} +Server-only pages must have a single root element. (HTML comments are considered elements as well.) +:: + ## Custom Routing As your app gets bigger and more complex, your routing might require more flexibility. For this reason, Nuxt directly exposes the router, routes and router options for customization in different ways.