Root Layout export #8702

ryanflorence · 2024-02-07T15:45:58Z

ryanflorence
Feb 7, 2024
Maintainer

The rendered root of the document is not a stable component type causing issues with the UX, primarily FOUC when <Links /> is removed and re-added. With the introduction of SPA mode, this UX issue is now critical to fix.

In the root route you can have the default export, an error boundary, and a hydrate fallback.

export default function App() {
  return (
    <html>
      <head>
        <Links />
      </head>
      <body>
        <Outlet />
        <Scripts />
      </body>
    </html>
  )
}

export function ErrorBoundary() {
  return (
    <html>
      <head>
        <Links />
      </head>
      <body>
        <h1>OH snap!</h1>
        <Scripts />
      </body>
    </html>
  )
}

export function HydrateFallback() {
  return (
    <html>
      <head>
        <Links />
      </head>
      <body>
        <h1>Loading...</h1>
        <Scripts />
      </body>
    </html>
  )
}

Each of these are rendered as the root of the app at different points in time:

hydrate(document, <RemixBrowser />);

// during hydration with a client loader it's really this
hydrate(document, <HydrateFallback />);

// if there's an error
hydrate(document, <ErrorBoundary />);

// if all good
hydrate(document, <App />);

Because the element.type changes when we flip from the HydrateFallback to the App, or from the App to the ErrorBoundary, all of the HTML is removed and remounted. React's reconciliation does not diff child elements of different component types (nor should it), for example:

// original
<div>
  <MyCoolComponent />
</div>

// next
<main>
  <MyCoolComponent />
</main>

React sees element.type has switched from div to main and replaces it causing MyCoolComponent to unmount and then mount again with a new parent. In the case of the root.tsx module, our entire document is replaced, including the <Links/>

Why this causes FOUC

In the case of stylesheets, the browser stops applying the styles when React removes the <Links/> from the previous root component, and then redownloads the styles when <Links /> is mounted again.

The problem is that the UI has been updated and rendered before the stylesheets have been downloaded again. This is different from an initial page load because the browser does not paint the page until all stylesheets have been loaded. When you're swapping styles in an out of an already loaded page it doesn't know how to wait.

With a route transition, Remix knows how to wait for any styles that are in the next route, but it can't know that for the root element switching from one type to another.

Previously this behavior was only noticed when an app had an unexpected error and the root error boundary was rendered. Since the app was already blowing up, the FOUC wasn't a major priority, or even really noticed by most developers since it seems many just use the default error boundary provided by Remix.

With clientLoaders, SPA mode, and HydrateFallback, this is now a major issue.

Solution

We simply need a stable root component that doesn't get unmounted when the app changes between the three states.

Today's workaround

Apps today can create a layout route in routes/ to fix this

root.tsx
routes/
  _layout.tsx
  _layout._index.tsx
  _layout.signup.tsx
  _layout.login.tsx
  _layout.etc.tsx

Root.tsx would look something like this:

export default function App() {
  return (
    <html>
      <head>
        <Links />
      </head>
      <body>
        <Outlet />
        <Scripts />
      </body>
    </html>
  )
}

And _layout.tsx

export default function App() {
  return <Outlet />
}

export function ErrorBoundary() {
  return <h1>OH snap!</h1>
}

export function HydrateFallback() {
  return  <h1>Loading...</h1>
}

Now the root.tsx with the <html>, <head>, and <Links/> will be stable as _layout flips between states, avoiding the problem.

Today's convention

I think every production Remix app I've seen has a Layout component in root.tsx to avoid repeating all of the html document parts:

function Layout({ children }) {
  return (
    <html>
      <head>
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <Scripts />
        <ScrollRestoration />
      </body>
    </html>
  )
}

export default function App() {
  return (
    <Layout>
      <Outlet />
    </Layout>
  )
}

export function ErrorBoundary() {
  return (
    <Layout>
      <h1>OH snap!</h1>
    </Layout>
  )
}

export function HydrateFallback() {
  return (
    <Layout>
      <h1>Loading...</h1>
    </Layout>
  )
}

This doesn't help the FOUC problem, but it's relevant to the proposal below.

Proposal

Instead of asking every Remix app to have a routes/_layout.tsx to fix the FOUC problem, we should embrace the community convention of the root Layout component.

// root.tsx
export function Layout({ children }) {
  return (
    <html>
      <head>
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <Scripts />
        <ScrollRestoration />
      </body>
    </html>
  )
}

If the app has supplied a Layout export in the root route, we'll use that as the root component. As the app swaps between the root default export, error boundary, and hydrate fallback in the layout children prop, the <Links/> remain stable.

Not only does this solve the problem, but most apps are already set up to use this API: simply export the Layout component they already have.

Can all routes export a layout?

No. They are already layouts themselves, this is only needed at the root since it has the unique challenge of being the definition of the entire document.

Default Layout

Remix could provide a default layout when none is supplied that looks like this:

export function Layout({ children }) {
  return (
    <html lang="en">
      <head>
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

And then apps wouldn't need to worry about the default document if they didn't want to.

alexanderson1993 · 2024-02-07T16:03:57Z

alexanderson1993
Feb 7, 2024

Remix could provide a default layout when none is supplied that looks like this:

With a default layout, would root.tsx go the way of entry.client.tsx and entry.server.tsx, where it isn't even necessary to be present in the filesystem? Remix could just fill it in if it didn't see a root.tsx in there.

It makes sense to me, since root.tsx is already a kind of entry.shared.tsx.

3 replies

rossipedia Feb 7, 2024

I really like this idea, it fits in well with the "levers" philosophy. You can have a happy-path app where all you have is a routes folder, with no root.tsx or entry.(client|server).tsx, and as you need more complex/bespoke solutions you just add the files and exports that you need.

sergiodxa Feb 7, 2024
Maintainer

I think app/root is already optional 🤔

brophdawg11 Feb 7, 2024
Maintainer

I talked to Ryan and for now we're foregoing the default Layout implementation since it would be a breaking change requiring a future flag and we're not sure if it makes sense in a future RSC world where <html>/<head> are likely only rendered on the server anyway so this entire thing may be a moot point. Plus we're not crazy about hiding the <html> tag from devs while hydrating the document.

brophdawg11 · 2024-02-08T16:47:49Z

brophdawg11
Feb 8, 2024
Maintainer

Added in #8709

3 replies

sergiodxa Feb 8, 2024
Maintainer

I think this is the fastest an RFC when from being opened as a discussion to closed after being implemented.

ajmeraaxesh Oct 22, 2024

@sergiodxa @brophdawg11 When using Tailwind as a CSS, we are sill seeing FOUC?

sergiodxa Oct 22, 2024
Maintainer

I never see FOUC with Tailwind, are you using LinksFunction to load it?

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Root Layout export #8702

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 2 comments 6 replies

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

Select a reply

Root Layout export #8702

ryanflorence Feb 7, 2024 Maintainer

Solution

Today's workaround

Today's convention

Proposal

Can all routes export a layout?

Default Layout

Replies: 2 comments · 6 replies

alexanderson1993 Feb 7, 2024

rossipedia Feb 7, 2024

sergiodxa Feb 7, 2024 Maintainer

brophdawg11 Feb 7, 2024 Maintainer

brophdawg11 Feb 8, 2024 Maintainer

sergiodxa Feb 8, 2024 Maintainer

ajmeraaxesh Oct 22, 2024

sergiodxa Oct 22, 2024 Maintainer

ryanflorence
Feb 7, 2024
Maintainer

Replies: 2 comments 6 replies

alexanderson1993
Feb 7, 2024

sergiodxa Feb 7, 2024
Maintainer

brophdawg11 Feb 7, 2024
Maintainer

brophdawg11
Feb 8, 2024
Maintainer

sergiodxa Feb 8, 2024
Maintainer

sergiodxa Oct 22, 2024
Maintainer