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 (that is, 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