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]

🦋 Changeset detected

Latest commit: 2c19d56

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@stackflow/react	Minor

Not sure what this means? Click here to learn what changesets are.

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

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added prepare function to the stackflow output, callable outside React components for preloading activity components and data
  • Accepts activity name and optional parameters; returns a promise with async error handling

• Refactor

  • usePrepare hook now delegates to shared implementation, maintaining existing behavior

Walkthrough

The PR extracts shared activity preparation logic into a reusable makePrepare factory and exposes it as a new prepare function on the stackflow() output, allowing component preload and data loader triggering outside React. The existing usePrepare hook is refactored to wrap this shared implementation.

Changes

Prepare API implementation and integration

Layer / File(s)	Summary
Type contract and public export integrations/react/src/Prepare.ts, integrations/react/src/index.ts	Defines the generic Prepare type (activity name + optional inferred params → Promise) and re-exports it from the package API.
Prepare factory implementation integrations/react/src/makePrepare.ts	Implements makePrepare factory that resolves activity configs, conditionally prefetches data via loaders and component _load methods, and preloads structured component content, aggregating all prefetch operations via Promise.all.
Prepare wired into stackflow output integrations/react/src/stackflow.tsx	Imports makePrepare and integrates prepare into StackflowOutput type and stackflow() function return, wiring the factory with config, loadData callback, and activity components.
Refactor usePrepare to wrap shared logic integrations/react/src/usePrepare.ts	Replaces inline prepare implementation with a memoized makePrepare call, consolidating all prefetch orchestration into the shared factory and removing duplicate logic.
API addition documentation .changeset/fep-2357-prepare-outside-react.md	Changeset describing the new prepare API behavior, parity with usePrepare semantics (no params warms only; params warm + fire loader), and promise-based error handling.

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: exposing a prepare function on the stackflow output for preloading activity components/data outside React context.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, explaining the problem solved, solution implemented, and design decisions with code examples.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 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: f70e16e

[cloudflare-workers-and-pages]

Deploying stackflow-demo with    Cloudflare Pages

Latest commit:	f70e16e
Status:	✅  Deploy successful!
Preview URL:	https://6d3065fa.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	f70e16e	Commit Preview URL	Jun 08 2026, 01:31 PM