diff --git a/packages/docs/src/pages/FAQ.mdx b/packages/docs/src/pages/FAQ.mdx index 4703420..c12cc51 100644 --- a/packages/docs/src/pages/FAQ.mdx +++ b/packages/docs/src/pages/FAQ.mdx @@ -1,5 +1,11 @@ # FAQ +## I'm seeing a ``The Root component renders other content next to `{children}` `` error + +With `ssr: false` (the default), the App is mounted into the parent element of `{children}` in your Root component, and React removes all other content from that element when mounting. This error means your Root component renders content that is silently removed this way in production builds. + +Make `{children}` the only content of its parent element in the Root component (for example, wrap it in a dedicated `
`). See [How It Works](/learn/how-it-works#keep-children-alone-in-its-parent-element) for details. + ## I'm seeing a `` must have a valid `as` value`` warning This is a bug in React itself. Please wait for [the fix](https://github.com/facebook/react/pull/34760) to be released. diff --git a/packages/docs/src/pages/GettingStarted.mdx b/packages/docs/src/pages/GettingStarted.mdx index 927cd01..fbf0704 100644 --- a/packages/docs/src/pages/GettingStarted.mdx +++ b/packages/docs/src/pages/GettingStarted.mdx @@ -65,6 +65,7 @@ The Root component: - is responsible for defining the shell HTML structure of your app - is a server component - **CANNOT** import client components; you could, but they are fully rendered into static HTML and never hydrated +- must render `{children}` as the only content of its parent element (unless SSR is enabled); see [How It Works](/learn/how-it-works#keep-children-alone-in-its-parent-element) ### 3. Create Your App Component diff --git a/packages/docs/src/pages/advanced/SSR.mdx b/packages/docs/src/pages/advanced/SSR.mdx index d845e13..5f00eb6 100644 --- a/packages/docs/src/pages/advanced/SSR.mdx +++ b/packages/docs/src/pages/advanced/SSR.mdx @@ -30,6 +30,10 @@ This improves perceived performance, especially on: The browser can start painting content as soon as the HTML arrives, while JavaScript loads in the background. Once loaded, React hydrates the existing HTML to make it interactive. +### No Root Layout Constraint + +Without SSR, `{children}` must be the only content of its parent element in the Root component ([details](/learn/how-it-works#keep-children-alone-in-its-parent-element)). With SSR enabled, the whole document is hydrated instead of mounting the App into a container element, so this constraint does not apply. + ## Cons ### Client Components Must Be SSR-Capable diff --git a/packages/docs/src/pages/learn/HowItWorks.mdx b/packages/docs/src/pages/learn/HowItWorks.mdx index 4364764..fa51da8 100644 --- a/packages/docs/src/pages/learn/HowItWorks.mdx +++ b/packages/docs/src/pages/learn/HowItWorks.mdx @@ -85,6 +85,44 @@ The Root component is special in two ways: The Root entrypoint is a FUNSTACK Static counterpart to the `index.html` file in traditional SPAs. It allows you to still leverage some of the benefits of server components for defining the HTML shell of your application. +### Keep `{children}` Alone in Its Parent Element + +With `ssr: false` (the default), the App is mounted on the client into the parent element of `{children}`. React clears all existing content of that element when mounting, so any other content the Root component renders **in the same element** is removed from the page the moment the App mounts: + +```tsx +// ❌ BAD:
and