feat(react): support activity component/data preload outside React runtime context

[ENvironmentSet]

Problem

Preloading an activity's resources before entering it — the lazy component chunk and the data described by the activity's loader — is currently only possible through the usePrepare hook.

Because usePrepare is a React hook, it depends on React Context (useConfig, useDataLoader, useActivityComponentMap) and can therefore only be called inside a mounted React tree. This makes it impossible to warm up chunks/data at the moments that matter most for initial-entry performance:

• app bootstrap, before the first render

In practice, consumers who need render-ahead preloading have had to reach for private APIs (e.g. the lazy component's internal _load), which is fragile and unsupported.

Solution

Expose the same preload capability as a plain function on the stackflow() output, alongside the existing render-outside APIs (actions, stepActions):

const { Stack, actions, stepActions, prepare } = stackflow({
  config,
  components,
  plugins,
});

// outside React — bootstrap
prepare("Article", { articleId: "123" }); // warm chunk + fire data loader
prepare("Article");                       // warm chunk only

Design decisions:

• Same instance, single source. prepare comes from the same stackflow() call as Stack/actions, so config and components never have to be passed twice and can never drift from the running instance. Since it does not touch the core store, it is usable from module-evaluation time — before <Stack> is mounted.
• Unchanged signature. The existing Prepare type is reused as-is: omitting activityParams preloads only the component chunk; passing params also fires the activity's data loader. The returned Promise<void> resolves when all fired preload work settles.
• Cache warming, not data injection. prepare does not store loader results; injecting loaderData into activities remains the loader plugin's responsibility.
• Failure semantics. Failures (unregistered activity, loader/chunk errors) are delivered as a rejection of the returned promise with the original reason — never a synchronous throw. A failed chunk load is retried on a subsequent prepare, so transient failures don't poison the cache. Fire-and-forget callers should attach .catch.
• usePrepare becomes a thin wrapper over the same implementation, so existing in-tree callers keep working unchanged.
• Type safety preserved. RegisteredActivityName / InferActivityParams<K> flow through unchanged, so invalid activity names or params remain compile-time errors.

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 51ad11d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ab159cd8-013f-434c-8236-158386ff7282

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/fep-2357

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

• @stackflow/demo

@stackflow/link

yarn add https://pkg.pr.new/@stackflow/link@716.tgz

@stackflow/plugin-basic-ui

yarn add https://pkg.pr.new/@stackflow/plugin-basic-ui@716.tgz

@stackflow/plugin-blocker

yarn add https://pkg.pr.new/@stackflow/plugin-blocker@716.tgz

@stackflow/plugin-google-analytics-4

yarn add https://pkg.pr.new/@stackflow/plugin-google-analytics-4@716.tgz

@stackflow/plugin-history-sync

yarn add https://pkg.pr.new/@stackflow/plugin-history-sync@716.tgz

@stackflow/plugin-lifecycle

yarn add https://pkg.pr.new/@stackflow/plugin-lifecycle@716.tgz

@stackflow/plugin-renderer-basic

yarn add https://pkg.pr.new/@stackflow/plugin-renderer-basic@716.tgz

@stackflow/plugin-renderer-web

yarn add https://pkg.pr.new/@stackflow/plugin-renderer-web@716.tgz

@stackflow/react-ui-core

yarn add https://pkg.pr.new/@stackflow/react-ui-core@716.tgz

@stackflow/react

yarn add https://pkg.pr.new/@stackflow/react@716.tgz

commit: 51ad11d

[cloudflare-workers-and-pages]

Deploying stackflow-demo with    Cloudflare Pages

Latest commit:	51ad11d
Status:	✅  Deploy successful!
Preview URL:	https://7e048082.stackflow-demo.pages.dev
Branch Preview URL:	https://feature-fep-2357.stackflow-demo.pages.dev

View logs

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	stackflow-docs	51ad11d	Commit Preview URL	Jun 04 2026, 11:26 AM