[Flight] Add approximate parent context for FormatContext #34601

sebmarkbage · 2025-09-25T14:31:16Z

Flight doesn't have any semantically sound notion of a parent context. That's why we removed Server Context. Each root can really start anywhere in the tree when you refetch subtrees. Additionally when you dedupe elements they can end up in multiple different parent contexts.

However, we do have a DEV only version of this with debugTask being tracked for the nearest parent element to track the context of properties inside of it.

To apply certain DOM specific hints and optimizations when you render host components we need some information of the context. This is usually very local so doesn't suffer from the likelihood that you refetch in the middle. We'll also only use this information for optimistic hints and not hard semantics so getting it wrong isn't terrible.

<picture>
  <img />
</picture>
<noscript>
  <p>
    <img />
  </p>
</noscript>

For example, in these cases we should exclude preloading the image but we have to know if that's the scope we're in.

We can easily get this wrong if they're split or even if they're wrapped in client components that we don't know about like:

<NoScript>
  <p>
    <img />
  </p>
</NoScript>

However, getting it wrong in either direction is not the end of the world. It's about covering the common cases well.

react-sizebot · 2025-09-25T14:35:03Z

The size diff is too large to display in a single comment. The GitHub action for this pull request contains an artifact called 'sizebot-message.md' with the full message.

Generated by 🚫 dangerJS against 6686619

[diff facebook/react@e2332183...b0c1dc01](facebook/react@e233218...b0c1dc0) <details> <summary>React upstream changes</summary> - facebook/react#34601 - facebook/react#34552 - facebook/react#34524 - facebook/react#34587 - facebook/react#34589 - facebook/react#34585 - facebook/react#34586 </details>

…#34604) In Fizz and Fiber we emit hints for suspensey images and CSS as soon as we discover them during render. At the beginning of the stream. This adds a similar capability when a Host Component is known to be a Host Component during the Flight render. The client doesn't know that these resources are in the payload until it parses that particular component which is lazy. So they need to be hoisted with hints. We detect when these are rendered during Flight and add them as hints. That allows you to consume a Flight payload to preload prefetched content without having to render it. `<link rel="preload">` can be hoisted more or less as is. `<link rel="stylesheet">` we preload but we don't actually insert them anywhere until they're rendered. We do these even for non-suspensey stylesheets since we know that when they're rendered they're going to start loading even if they're not immediately used. They're never lazy. `<img src>` we only preload if they follow the suspensey image pattern since otherwise they may be more lazy e.g. by if they're in the viewport. We also skip if they're known to be inside `<picture>`. Same as Fizz. Ideally this would preload the other `<source>` but it's tricky. The downside of this is that you might conditionally render something in only one branch given a client component. However, in that case you're already eagerly fetching the server component's data in that branch so it's not too much of a stretch that you want to eagerly fetch the corresponding resources as well. If you wanted it to be lazy, you should've done a lazy fetch of the RSC. We don't collect hints when any of these are wrapped in a Client Component. In those cases you might want to add your own preload to a wrapper Shared Component. Everything is skipped if it's known to be inside `<noscript>`. Note that the format context is approximate (see #34601) so it's possible for these hints to overfetch or underfetch if you try to trick it. E.g. by rendering Server Components inside a Client Component that renders `<noscript>`. --------- Co-authored-by: Josh Story <josh.c.story@gmail.com>

…4601) Flight doesn't have any semantically sound notion of a parent context. That's why we removed Server Context. Each root can really start anywhere in the tree when you refetch subtrees. Additionally when you dedupe elements they can end up in multiple different parent contexts. However, we do have a DEV only version of this with debugTask being tracked for the nearest parent element to track the context of properties inside of it. To apply certain DOM specific hints and optimizations when you render host components we need some information of the context. This is usually very local so doesn't suffer from the likelihood that you refetch in the middle. We'll also only use this information for optimistic hints and not hard semantics so getting it wrong isn't terrible. ``` <picture> <img /> </picture> <noscript> <img /> </noscript> ``` For example, in these cases we should exclude preloading the image but we have to know if that's the scope we're in. We can easily get this wrong if they're split or even if they're wrapped in client components that we don't know about like: ``` <NoScript> <img /> </NoScript> ``` However, getting it wrong in either direction is not the end of the world. It's about covering the common cases well. DiffTrain build for [b0c1dc0](facebook@b0c1dc0)

…facebook#34604) In Fizz and Fiber we emit hints for suspensey images and CSS as soon as we discover them during render. At the beginning of the stream. This adds a similar capability when a Host Component is known to be a Host Component during the Flight render. The client doesn't know that these resources are in the payload until it parses that particular component which is lazy. So they need to be hoisted with hints. We detect when these are rendered during Flight and add them as hints. That allows you to consume a Flight payload to preload prefetched content without having to render it. `<link rel="preload">` can be hoisted more or less as is. `<link rel="stylesheet">` we preload but we don't actually insert them anywhere until they're rendered. We do these even for non-suspensey stylesheets since we know that when they're rendered they're going to start loading even if they're not immediately used. They're never lazy. `<img src>` we only preload if they follow the suspensey image pattern since otherwise they may be more lazy e.g. by if they're in the viewport. We also skip if they're known to be inside `<picture>`. Same as Fizz. Ideally this would preload the other `<source>` but it's tricky. The downside of this is that you might conditionally render something in only one branch given a client component. However, in that case you're already eagerly fetching the server component's data in that branch so it's not too much of a stretch that you want to eagerly fetch the corresponding resources as well. If you wanted it to be lazy, you should've done a lazy fetch of the RSC. We don't collect hints when any of these are wrapped in a Client Component. In those cases you might want to add your own preload to a wrapper Shared Component. Everything is skipped if it's known to be inside `<noscript>`. Note that the format context is approximate (see facebook#34601) so it's possible for these hints to overfetch or underfetch if you try to trick it. E.g. by rendering Server Components inside a Client Component that renders `<noscript>`. --------- Co-authored-by: Josh Story <josh.c.story@gmail.com> DiffTrain build for [047715c](facebook@047715c)

…4601) Flight doesn't have any semantically sound notion of a parent context. That's why we removed Server Context. Each root can really start anywhere in the tree when you refetch subtrees. Additionally when you dedupe elements they can end up in multiple different parent contexts. However, we do have a DEV only version of this with debugTask being tracked for the nearest parent element to track the context of properties inside of it. To apply certain DOM specific hints and optimizations when you render host components we need some information of the context. This is usually very local so doesn't suffer from the likelihood that you refetch in the middle. We'll also only use this information for optimistic hints and not hard semantics so getting it wrong isn't terrible. ``` <picture> <img /> </picture> <noscript> <img /> </noscript> ``` For example, in these cases we should exclude preloading the image but we have to know if that's the scope we're in. We can easily get this wrong if they're split or even if they're wrapped in client components that we don't know about like: ``` <NoScript> <img /> </NoScript> ``` However, getting it wrong in either direction is not the end of the world. It's about covering the common cases well.

…facebook#34604) In Fizz and Fiber we emit hints for suspensey images and CSS as soon as we discover them during render. At the beginning of the stream. This adds a similar capability when a Host Component is known to be a Host Component during the Flight render. The client doesn't know that these resources are in the payload until it parses that particular component which is lazy. So they need to be hoisted with hints. We detect when these are rendered during Flight and add them as hints. That allows you to consume a Flight payload to preload prefetched content without having to render it. `<link rel="preload">` can be hoisted more or less as is. `<link rel="stylesheet">` we preload but we don't actually insert them anywhere until they're rendered. We do these even for non-suspensey stylesheets since we know that when they're rendered they're going to start loading even if they're not immediately used. They're never lazy. `<img src>` we only preload if they follow the suspensey image pattern since otherwise they may be more lazy e.g. by if they're in the viewport. We also skip if they're known to be inside `<picture>`. Same as Fizz. Ideally this would preload the other `<source>` but it's tricky. The downside of this is that you might conditionally render something in only one branch given a client component. However, in that case you're already eagerly fetching the server component's data in that branch so it's not too much of a stretch that you want to eagerly fetch the corresponding resources as well. If you wanted it to be lazy, you should've done a lazy fetch of the RSC. We don't collect hints when any of these are wrapped in a Client Component. In those cases you might want to add your own preload to a wrapper Shared Component. Everything is skipped if it's known to be inside `<noscript>`. Note that the format context is approximate (see facebook#34601) so it's possible for these hints to overfetch or underfetch if you try to trick it. E.g. by rendering Server Components inside a Client Component that renders `<noscript>`. --------- Co-authored-by: Josh Story <josh.c.story@gmail.com>

Add approximate parent context for FormatContext

6686619

sebmarkbage requested a review from unstubbable September 25, 2025 14:31

meta-cla bot added the CLA Signed label Sep 25, 2025

github-actions bot added the React Core Team Opened by a member of the React Core Team label Sep 25, 2025

unstubbable approved these changes Sep 25, 2025

View reviewed changes

sebmarkbage merged commit b0c1dc0 into facebook:main Sep 25, 2025
247 checks passed

nextjs-bot mentioned this pull request Sep 25, 2025

Upgrade React from e2332183-20250924 to b0c1dc01-20250925 vercel/next.js#84248

Merged

sebmarkbage mentioned this pull request Sep 26, 2025

[Flight] Preload <img> and <link> using hints before they're rendered #34604

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Flight] Add approximate parent context for FormatContext #34601

[Flight] Add approximate parent context for FormatContext #34601

sebmarkbage commented Sep 25, 2025 •

edited by unstubbable

Loading

Uh oh!

react-sizebot commented Sep 25, 2025

Uh oh!

Uh oh!

Uh oh!

[Flight] Add approximate parent context for FormatContext #34601

[Flight] Add approximate parent context for FormatContext #34601

Conversation

sebmarkbage commented Sep 25, 2025 • edited by unstubbable Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

react-sizebot commented Sep 25, 2025

Uh oh!

Uh oh!

Uh oh!

sebmarkbage commented Sep 25, 2025 •

edited by unstubbable

Loading