Add Suspense support for useFlag loading

[roncohen]

Adds Suspense support to useFlag in @reflag/react-sdk.

Users can now opt into Suspense loading behavior either at the provider level:

<ReflagProvider suspense>
  <Suspense fallback={<Loading />}>
    <App />
  </Suspense>
</ReflagProvider>

or per hook call:

  useFlag("huddle", { suspense: true });

When enabled, useFlag throws a loading promise while isLoading is true, allowing the nearest React boundary to render its fallback until flags finish loading.

[Copilot]

🟡 Not ready to approve

The current Suspense promise can hang indefinitely on initialization failures, and the new hook-level override behavior is not covered by tests/documentation precisely enough.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Pull request overview

Adds React Suspense-based loading support to @reflag/react-sdk’s useFlag, allowing consumers to opt into Suspense either via provider props or per-hook options so loading UI can be controlled by the nearest <Suspense> boundary.

Changes:

• Adds suspense support to providers and useFlag/useFeature, including a provider-managed loading promise used for Suspense.
• Introduces UseFlagOptions with a per-hook suspense override that can opt in/out relative to provider defaults.
• Documents Suspense usage and adds a new test for provider-level Suspense behavior.

File summaries

File	Description
packages/react-sdk/src/index.tsx	Implements provider-level and per-hook Suspense behavior for useFlag, including loading promise management.
packages/react-sdk/test/usage.test.tsx	Adds a Suspense test verifying fallback rendering while flags are loading.
packages/react-sdk/README.md	Documents the new suspense option and provides a Suspense usage example.
.changeset/green-flowers-suspend.md	Declares a minor release for the new Suspense support.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 3
• Review effort level: Lite

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.