docs: clarify options prop requirement for Pages Router SSR with serverState

[talissoncosta]

Description

Problem

The current Next.js Pages Router SSR documentation example shows how to use serverState but doesn't mention that the options prop is required for automatic client-side initialization.

This leads to a common issue where developers following the docs experience:

• useFlagsmithLoading() stuck on { isLoading: true, isFetching: true }
• Loading states never updating
• Confusion about why hooks don't work as expected

Root Cause

The FlagsmithProvider component has an intentional design contract:

// From react.tsx type definition
options?: Parameters<IFlagsmith['init']>[0] // Initialisation options, if you do not provide this you will have to call init manually

• Without options: Users must call flagsmith.init() manually
• With options: Component automatically calls init() on mount

This design is intentional but not documented in the Pages Router example.

Current Documentation Gap

The current example shows:

<FlagsmithProvider
  flagsmith={flagsmithRef.current}
  serverState={flagsmithState}
>
  <Component {...pageProps} />
</FlagsmithProvider>

Issue: This works for rendering flags, but hooks like useFlagsmithLoading() will be stuck because init() was never called to register callbacks.

What Needs to Be Documented

The documentation should clearly explain:

1. The options prop is required for automatic client-side initialization
2. When using serverState, you should pass options={{ preventFetch: true }}
3. Why preventFetch: true is recommended (avoids duplicate API calls, uses server-side flags)
4. What happens without options (hooks won't work, manual init() required)

---

Suggested Fix

Update the Pages Router documentation example to:

• Include options={{ preventFetch: true }} in the code example
• Add a callout/note explaining why it's needed for hooks to work
• Explain the consequence of omitting it (stuck loading states)

Note: The code already has a comment in the type definition (react.tsx:10), but the documentation doesn't reflect this requirement.

---

Additional Context

User Impact

This affects developers:

• Following the Pages Router SSR documentation
• Using useFlagsmithLoading() or other hooks
• New to Flagsmith (not familiar with the initialization contract)

Customer Report

A customer recently reported this exact issue:

• Using Next.js 15 Pages Router
• Following the docs exactly as written
• useFlagsmithLoading() stuck on loading state
• Adding options={{ preventFetch: true }} immediately fixed it

Reproduction

I've created a minimal reproduction project that demonstrates:

1. The issue when options is omitted
2. The fix when options={{ preventFetch: true }} is added

---

Acceptance Criteria

• Pages Router example updated to include options={{ preventFetch: true }}
• Clear note/callout added explaining why options is required
• Documentation explains what happens without the options prop

---

Related Code

• Component type definition: react.tsx:8-13
• Initialization logic: react.tsx:35-54