mirror of
https://github.com/facebook/react.git
synced 2025-11-01 09:12:30 +00:00
Josh StoryandGitHub
b25bcd460f
Suspense is meant to be composable but there has been a lonstanding
limitation with using Suspense above the `<body>` tag of an HTML
document due to peculiarities of how HTML is parsed. For instance if you
used Suspense to render an entire HTML document and had a fallback that
might flush an alternate Document the comment nodes which describe this
boundary scope won't be where they need to be in the DOM for client
React to properly hydrate them. This is somewhat a problem of our own
making in that we have a concept of a Preamble and we leave the closing
body and html tags behind until streaming has completed which produces a
valid HTML document that also matches the DOM structure that would be
parsed from it. However Preambles as a concept are too important to
features like Float to imagine moving away from this model and so we can
either choose to just accept that you cannot use Suspense anywhere
except inside the `<body>` or we can build special support for Suspense
into react-dom that has a coherent semantic with how HTML documents are
written and parsed.
This change implements Suspense support for react-dom/server by
correctly serializing boundaries during rendering, prerendering, and
resumgin on the server. It does not yet support Suspense everywhere on
the client but this will arrive in a subsequent change. In practice
Suspense cannot be used above the `<body>` tag today so this is not a
breaking change since no programs in the wild could be using this
feature anyway.
React's streaming rendering of HTML doesn't lend itself to replacing the
contents of the documentElement, head, or body of a Document. These are
already special cased in fiber as HostSingletons and similarly for Fizz
the values we render for these tags must never be updated by the Fizz
runtime once written. To accomplish these we redefine the Preamble as
the tags that represent these three singletons plus the contents of the
document.head. If you use Suspense above any part of the Preamble then
nothing will be written to the destination until the boundary is no
longer pending. If the boundary completes then the preamble from within
that boudnary will be output. If the boundary postpones or errors then
the preamble from the fallback will be used instead.
Additionally, by default anything that is not part of the preamble is
implicitly in body scope. This leads to the somewhat counterintuitive
consequence that the comment nodes we use to mark the borders of a
Suspense boundary in Fizz can appear INSIDE the preamble that was
rendered within it.
```typescript
render((
<Suspense>
<html lang="en">
<body>
<div>hello world</div>
</body>
</html>
</Suspense>
))
```
will produce an HTML document like this
```html
<!DOCTYPE html>
<html lang="en">
<head></head>
<body>
<!--$--> <-- this is the comment Node representing the outermost Suspense
<div>hello world</div>
<$--/$-->
</body>
</html>
```
Later when I update Fiber to support Suspense anywhere hydration will
similarly start implicitly in the document body when the root is part of
the preamble (the document or one of it's singletons).
100 lines
4.2 KiB
JavaScript
100 lines
4.2 KiB
JavaScript
/**
|
|
* Copyright (c) Meta Platforms, Inc. and affiliates.
|
|
*
|
|
* This source code is licensed under the MIT license found in the
|
|
* LICENSE file in the root directory of this source tree.
|
|
*
|
|
* @flow
|
|
*/
|
|
|
|
// This is a host config that's used for the `react-server` package on npm.
|
|
// It is only used by third-party renderers.
|
|
//
|
|
// Its API lets you pass the host config as an argument.
|
|
// However, inside the `react-server` we treat host config as a module.
|
|
// This file is a shim between two worlds.
|
|
//
|
|
// It works because the `react-server` bundle is wrapped in something like:
|
|
//
|
|
// module.exports = function ($$$config) {
|
|
// /* renderer code */
|
|
// }
|
|
//
|
|
// So `$$$config` looks like a global variable, but it's
|
|
// really an argument to a top-level wrapping function.
|
|
|
|
import type {Request} from 'react-server/src/ReactFizzServer';
|
|
import type {TransitionStatus} from 'react-reconciler/src/ReactFiberConfig';
|
|
|
|
declare const $$$config: any;
|
|
export opaque type Destination = mixed;
|
|
export opaque type RenderState = mixed;
|
|
export opaque type HoistableState = mixed;
|
|
export opaque type ResumableState = mixed;
|
|
export opaque type PreambleState = mixed;
|
|
export opaque type FormatContext = mixed;
|
|
export opaque type HeadersDescriptor = mixed;
|
|
export type {TransitionStatus};
|
|
|
|
export const isPrimaryRenderer = false;
|
|
|
|
export const supportsClientAPIs = true;
|
|
|
|
export const supportsRequestStorage = false;
|
|
export const requestStorage: AsyncLocalStorage<Request | void> = (null: any);
|
|
|
|
export const bindToConsole = $$$config.bindToConsole;
|
|
|
|
export const resetResumableState = $$$config.resetResumableState;
|
|
export const completeResumableState = $$$config.completeResumableState;
|
|
export const getChildFormatContext = $$$config.getChildFormatContext;
|
|
export const makeId = $$$config.makeId;
|
|
export const pushTextInstance = $$$config.pushTextInstance;
|
|
export const pushStartInstance = $$$config.pushStartInstance;
|
|
export const pushEndInstance = $$$config.pushEndInstance;
|
|
export const pushSegmentFinale = $$$config.pushSegmentFinale;
|
|
export const pushFormStateMarkerIsMatching =
|
|
$$$config.pushFormStateMarkerIsMatching;
|
|
export const pushFormStateMarkerIsNotMatching =
|
|
$$$config.pushFormStateMarkerIsNotMatching;
|
|
export const writeCompletedRoot = $$$config.writeCompletedRoot;
|
|
export const writePlaceholder = $$$config.writePlaceholder;
|
|
export const writeStartCompletedSuspenseBoundary =
|
|
$$$config.writeStartCompletedSuspenseBoundary;
|
|
export const writeStartPendingSuspenseBoundary =
|
|
$$$config.writeStartPendingSuspenseBoundary;
|
|
export const writeStartClientRenderedSuspenseBoundary =
|
|
$$$config.writeStartClientRenderedSuspenseBoundary;
|
|
export const writeEndCompletedSuspenseBoundary =
|
|
$$$config.writeEndCompletedSuspenseBoundary;
|
|
export const writeEndPendingSuspenseBoundary =
|
|
$$$config.writeEndPendingSuspenseBoundary;
|
|
export const writeEndClientRenderedSuspenseBoundary =
|
|
$$$config.writeEndClientRenderedSuspenseBoundary;
|
|
export const writeStartSegment = $$$config.writeStartSegment;
|
|
export const writeEndSegment = $$$config.writeEndSegment;
|
|
export const writeCompletedSegmentInstruction =
|
|
$$$config.writeCompletedSegmentInstruction;
|
|
export const writeCompletedBoundaryInstruction =
|
|
$$$config.writeCompletedBoundaryInstruction;
|
|
export const writeClientRenderBoundaryInstruction =
|
|
$$$config.writeClientRenderBoundaryInstruction;
|
|
export const NotPendingTransition = $$$config.NotPendingTransition;
|
|
export const createPreambleState = $$$config.createPreambleState;
|
|
export const canHavePreamble = $$$config.canHavePreamble;
|
|
export const isPreambleContext = $$$config.isPreambleContext;
|
|
export const isPreambleReady = $$$config.isPreambleReady;
|
|
export const hoistPreambleState = $$$config.hoistPreambleState;
|
|
|
|
// -------------------------
|
|
// Resources
|
|
// -------------------------
|
|
export const writePreambleStart = $$$config.writePreambleStart;
|
|
export const writePreambleEnd = $$$config.writePreambleEnd;
|
|
export const writeHoistables = $$$config.writeHoistables;
|
|
export const writeHoistablesForBoundary = $$$config.writeHoistablesForBoundary;
|
|
export const writePostamble = $$$config.writePostamble;
|
|
export const hoistHoistables = $$$config.hoistHoistables;
|
|
export const createHoistableState = $$$config.createHoistableState;
|
|
export const emitEarlyPreloads = $$$config.emitEarlyPreloads;
|