Library Upgrade Guide: <head> (e.g. react-helmet) #106

sebmarkbage · 2021-10-06T18:29:08Z

sebmarkbage
Oct 6, 2021
Maintainer

Library Upgrade Guide: `<head>`

This is an upgrade guide for libraries like react-helmet, next/head etc. I.e. libraries that collect tags like <meta>, <title>, <link rel="apple-touch-icon"> and <link rel="canonical"> by rendering them in components and then extracting them to the head.

I don't include inserting <link rel="stylesheet">, <style> or <script> into the head for this use case. There are follow up guides for <link ref="stylesheet" />, <style> and <script> loading. Our recommendation is that <head> libraries don't support this use case and instead direct this problem space to CSS and script specific solutions. You can support ad-hoc inserting random scripts/css this way but not as a general purpose solution. This is mostly already the case.

The use case for <head> is a 1:1 correspondence with the URL. It's meta data for decorating the URL - for a social media preview, for SEO, for showing a bookmark, or for display in the current browser tab title.

Injecting Into the SSR Stream

Typically this technique is done by collecting data while rendering and then combining the result at the end like:

"<!doctype html><html><head>" + head + "</head><body>" + content + "</body>"

In React 18, renderToString is discouraged and instead the new stream API is preferred which doesn't work with this technique.

Instead, we recommend amending the stream before React writes its shell content.

writable.write('<!doctype html><html><head>');
const stream = renderToPipeableStream(<App />, {
  onShellReady() {
    writable.write(head);
    writable.write('</head><body>');
  }
});
stream.pipe(writable);

This ensures that React can start emitting preload tags into the head early, and once it has rendered its shell, you can collect the head and emit it before React writes the rest of the HTML.

For a Web Stream, you can use an intermediate custom ReadableStream. Something like this:

let reader;
const stream = new ReadableStream({
  start(controller) {
    controller.enqueue(textEncoder.encode('<!doctype html><html><head>'));
    reader = renderToReadableStream(<App>, {
      onCompleteShell() {
        controller.enqueue(textEncoder.encode(head));
        controller.enqueue(textEncoder.encode('</head><body>'))
      }
    }).getReader();
  },
  pull(controller) {
    ...
  },
  cancel() {
    reader.cancel();
  }
});

or maybe a TransformStream:

let controller;
let shouldInjectHead;
let readable = renderToReadableStream(<App>, {
  onCompleteShell() {
    shouldInjectHead = true;
  };
});
const injectHead = new TransformStream({
  start(controller) {
    controller.enqueue(textEncoder.encode('<!doctype html><html><head>'));
  },
  transform(chunk, controller) {
    if (shouldInjectHead) {
      shouldInjectHead = false;
      controller.enqueue(textEncoder.encode(head));
      controller.enqueue(textEncoder.encode('</head><body>'))
    }
    controller.enqueue(chunk);
  },
});
readable.pipeThrough(injectHead);

You can only emit what React has rendered so far. However, if something suspended, React might not have rendered the whole tree yet. React will still start emitting HTML for the partial HTML. In that case, the <head> you emit at onCompleteShell might not be the final.

When to Start the Stream

Unfortunately, most specs specify that <head> tags requires them to be first in the HTML stream before any visual content. This is bad since it requires compromising on display performance of the main content, by putting content that's invisible first. Hopefully we can one day ensure that all implementations respect title and meta tags all the way through the document (which most do).

Similarly, for SEO purposes it might be important to accurately reflect a 301 or 500 HTTP status code.

You can choose to hold React back from streaming if you want and start streaming later. In general we don't recommend this for best performance, but it can be useful if the User-Agent is a known bot that doesn't support JavaScript. We recommend looking at th user agent header and if it's a bot delay the stream until the onAllReady callback. That ensures that you have the full HTML ready all at once - including any overrides to the <head>.

const stream = renderToPipeableStream(<App />, {
  onError(error) {
    response.statusCode = 500;
  }
  onAllReady() {
    writable.write('<!doctype html><html><head>');
    writable.write(head);
    writable.write('</head><body>');
    stream.pipe(writable);
  }
});

In this case React can't stream preload tags early but that's because if you want to reliably set the status code, you have to wait until you're sure you won't error anymore.

For non-bots we recommend just leaving the <head> in whatever partial state was reached when React started rendering. That way you get a best effort and depending on how fast things load and whether you have any overrides - it might be the final. If it's not, then let hydration patch it up.

It might be tempting to emit scripts that update the <head> into the stream as new heads are discovered. However, that gets complicated since the client might start hydrating and navigating away before the stream is complete. Therefore, we recommend not doing this and instead just always override it when the client component mounts.

Another technique is to wait for the first <Head> before starting streaming. That way if the first <Head> is deep in the tree, you won't get the benefit of streaming up until that point but at least the rest of the page is streaming. This is not necessarily best for SEO purposes since it still uses JS for streaming, but can be used as a compromise if you want to support unknown User Agents while compromising on end-user performance.

Selective Hydration

On the client React 18 will partially hydrate at the Suspense boundary level. This can cause an interesting effect if your system attempts to merge multiple heads and supports conflict resolution. E.g. if you have a parent provide defaults and a child can override it.

Imagine a structure like this:

<>
  <Head>
    <title>Site</title>
  </Head>
  <Suspense fallback="Loading...">
    <Head>
      <title>Site - Page</title>
    </Head>
    ...
  </Suspense>
</>

React will first hydrate the outer <title>Site</title> and triggers its life-cycles/effects. Then later it'll come back around to hydrate the inner content: <title>Site - Page</title>.

We recommend that your library always override whatever was in the original HTML when hydrating for this use case.

However, that can lead to a quirky effect in this scenario. If the server had rendered <title>Site - Page</title> then the title can temporarily update to Site and then later back to Site - Page while hydrating.

To avoid this we recommend just having a single <Head> or putting them all in the same Suspense boundary.

Preload tags

In the future we'd like to enable React to emit <link rel="preload"> tags as soon as possible into the stream. As long as you don't need to set the HTTP status code, these can be emitted even before the other head tags as discovered. As a result, it's not necessarily a good idea to delay the whole stream unless the status code is important.

In particular, for a logged-in user that can't be a bot or a UA that's not a bot, we recommend starting the stream as soon as possible by calling pipe() immediately.

Future

In a future minor we'd like to add built-in support for <head> directly in React. That way you can easily render the whole document using React and avoid a lot of the extra plumbing.

However, the best idea we have right now is that it would not merge the content (unlike react-helmet and next/head). Instead it'd be the last <head> that wins but we'd recommend only having one on the page at any given time. Instead defaults can be provided through Context from above. We'd also have the ability to specify a default-head at the root that can be used as a fallback if the stream starts early - e.g. to set a default title.

Another change is that it would not reset the <head> when it's unmounted. Instead it would leave it on the old value. That way if you're navigating between two pages, and the new <head> doesn't immediately load (e.g. it's suspended), then it doesn't temporarily flash the old value. It is expected that this API would be used together with a router to ensure that you pair one <head> to one route.

This would be backwards compatible since if you SSR <head> today it would keep working pretty much the same, and you already can't use it on the client unless you're hydrating SSR:ed content.

sebmarkbage · 2021-10-06T18:51:24Z

sebmarkbage
Oct 6, 2021
Maintainer Author

One compromise that's good if you want to avoid UA detection:

Don't bother with 5xx status codes for errors inside React. Just use that status code if your whole JS environment is broken for example. Instead of just a component errors. That code is mostly useful to avoid updating a search engine index with transient errors. If it's a bug in the component, it's unlikely to be transient. It might still error due to a transient data access error which would be unfortunate. However, the search engine bot will eventually fix it once it comes back around later with a JS aware sweep.
Don't use 301 status codes with a deep redirect (like react-router). Instead ensure that permanent redirects like that can be done through 1:1 mappings without rendering the page.
Place your <head> components near but above the first <Suspense> boundary. That ensures you can parallelize everything else. Since it might be slow to load things like page description, this can negatively affect perf of your app compared to placing it lower in the tree. This assumes you're using suspensey data to load the data. If you're not, then you're likely blocking streaming on data anyway.

That way the head is always included in the first React shell but you can stream the rest of the page.

0 replies

devknoll · 2021-11-30T17:07:39Z

devknoll
Nov 30, 2021
Collaborator

However, the best idea we have right now is that it would not merge the content (unlike react-helmet and next/head). Instead it'd be the last that wins but we'd recommend only having one on the page at any given time. Instead defaults can be provided through Context from above. We'd also have the ability to specify a default-head at the root that can be used as a fallback if the stream starts early - e.g. to set a default title.

@sebmarkbage I've been thinking about this a bit lately. This approach might actually make it difficult to migrate to from the existing approach that is explicitly recommended in this post (i.e. waiting until onCompleteShell) to one where React renders the entire document. That's because with the current recommendation, <head> is still a side effect of rendering <App />, where the future approach would require it to be provided before <App> is rendered in order to get the same behavior, which would be a pretty significant difference (i.e. one would support suspense APIs to generate the head, the other would require migrating to a different approach).

Instead of explicit support for passing in a default <head> at the top-level, I wonder if it might be preferable to just support an option to tell React to wait until a first <head> is rendered before writing to the stream. The ideal case of a default that is available early would just be solved by rendering that first <head> as early as possible (e.g. as the first child of the rendered element), potentially with warnings if it appears late.

As an alternative, allowing that default head value that is provided up front to be a promise that can run concurrently with the rendering of the document would also be acceptable, I think.

2 replies

sebmarkbage Nov 30, 2021
Maintainer Author

I suspect migrating to this model from existing models to be a bit bumpy. Especially since providing defaults require a parent Context provider where as existing API is a sibling. However you can migrate to this model today and have it work in the future.

The idea is that the default head would never be used on the client since it'll always just be the previously active head until a new head is rendered. So the idea is that you shouldn't include that part in your client code. It's outside the app.

Waiting for the first <head> wouldn't work because the idea is that you only have one <head> at a time so that means couldn't have any deeper ones.

It could work for the first <default-head> or something. It's tempting to put a lot of complex logic to power it where as the intention is really to have a very static global site kind of head there that possibly isn't even route dependent so that it can be immediate. So even in that scenario we should probably require one at the root too that can be flushed early. It could still suspend though.

If you reach the first terminal/canonical <head> before flushing, it'll be the one that wins regardless. So it's not super essential to have the default be completely accurate.

So the question is, if you have a global default and in most cases the canonical <head> wins anyway. Is it important to also have intermediate defaults that can refine the default further until the canonical one loads? Is it worth having that if the code to power it also ends up on the client?

devknoll Nov 30, 2021
Collaborator

Hmmmm. Let me keep thinking about it -- I think I might be confusing things a bit, because I think it also highly depends on where you are suspending. For example, no changes would be necessary to the original API if you could generate that default head as a side effect of a Server Component render, since the Client Component tree is completely separate, and you could just wait for that side effect (in user space) before rendering that (Client Component) tree if you really wanted to.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Library Upgrade Guide: <head> (e.g. react-helmet) #106

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 2 comments 2 replies

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Select a reply

Library Upgrade Guide: <head> (e.g. react-helmet) #106

sebmarkbage Oct 6, 2021 Maintainer

Library Upgrade Guide: <head>

Injecting Into the SSR Stream

When to Start the Stream

Selective Hydration

Preload tags

Future

Replies: 2 comments · 2 replies

sebmarkbage Oct 6, 2021 Maintainer Author

devknoll Nov 30, 2021 Collaborator

sebmarkbage Nov 30, 2021 Maintainer Author

devknoll Nov 30, 2021 Collaborator

sebmarkbage
Oct 6, 2021
Maintainer

Library Upgrade Guide: `<head>`

Replies: 2 comments 2 replies

sebmarkbage
Oct 6, 2021
Maintainer Author

devknoll
Nov 30, 2021
Collaborator

sebmarkbage Nov 30, 2021
Maintainer Author

devknoll Nov 30, 2021
Collaborator