Warning
This is an internal project, and is not intended for public use. No support or stability guarantees are provided.
Layout-level providers for the Coordinated Lazy system: a ChunkProvider that supplies a lazily-imported client source, and a PreloadProvider that dedups speculative imports across instances. Both follow the Props Context Layering pattern — like CodeProvider does for the code highlighter.
Supplies a client StreamSource to descendant chunks, dynamically importing the loader module only when a chunk first needs to load — so the loaders stay out of the initial bundle and are never imported when chunks are precomputed/preloaded. The import promise is cached, so many chunks share one fetch.
<ChunkProvider source={() => import('./chartSource')}>
<Chart />
</ChunkProvider>
A chunk with no config source resolves its loader from the surrounding ChunkProvider; a preloaded chunk never triggers the import at all.
Layout-level provider that supplies a client StreamSource to descendant
chunks, dynamically importing the loader module only when a chunk first needs
to load — so the loaders stay out of the initial bundle and are never
imported when chunks are precomputed/preloaded. The import promise is cached,
so many chunks share one fetch (mirrors how CodeProvider lazily provides
its parser/loaders).
| Prop | Type | Description |
|---|---|---|
| source | | Dynamic import of the client source module — its |
| children | |
usePreload() returns a function that memoizes a dynamic import by key, so many instances that need the same helper share one import() (and one round of any work the factory does). Use it inside a CoordinatedLazy preload(hoisted) callback to start importing the helpers a chunk's data implies, in parallel with loading the content:
const preload = usePreload();
<CoordinatedLazy
ready={ready}
fallback={<Loading />}
content={<Content />}
preload={(hoisted) => {
if (hoisted.needsTransform) {
preload('transform', () => import('./transform'));
}
}}
/>Without a PreloadProvider, usePreload falls back to calling the factory directly (the browser's module cache still dedups identical imports); the provider adds the cross-instance memo of the factory's own work.
Scopes a cross-instance preload cache (typically at a layout). Descendants
call usePreload to start dynamic imports of shared helpers keyed by a
stable string; the first call per key runs the factory and every other
instance reuses its promise — so a helper a chunk’s data implies (a transform
fn, say) is fetched once, in parallel with the content, across the page.
| Prop | Type | Description |
|---|---|---|
| children | |
Returns the cross-instance PreloadFn from the surrounding
PreloadProvider, or a direct-call fallback when there is none. Use it inside
a CoordinatedLazy preload(hoisted) callback to start importing helpers the
hoisted data implies, deduped across every instance on the page.
Supplies the lazily-resolved client StreamSource to descendant chunks.
undefined outside a ChunkProvider — a chunk then relies on its own config
source (or stays in its loading/preloaded state).
type ChunkContext = React.Context<ChunkContextValue | undefined>Provided by a ChunkProvider: lazily resolve the client StreamSource for
descendant chunks. Called only when a chunk actually needs to load (i.e. it
was not preloaded), so the loader module stays out of the initial bundle and
is never imported when everything is precomputed.
type ChunkContextValue<P = unknown, O = unknown> = {
resolveSource: () => Promise<StreamSource<P, O>>;
}Props for ChunkProvider.
type ChunkProviderProps<P = unknown, O = unknown> = {
children: React.ReactNode;
/**
* Dynamic import of the client source module - its `default` export is the
* `StreamSource`. Imported once, lazily, on the first chunk that needs
* to load; the resolved promise is shared across descendants.
*/
source: () => Promise<{ default: StreamSource<P, O> }>;
}Provides the cross-instance PreloadFn. undefined outside a
PreloadProvider — usePreload then falls back to calling the factory
directly (the browser’s module cache still dedups identical import()s).
type PreloadContext = React.Context<PreloadFn | undefined>preload callback