Flagsmith / Flagsmith/flagsmith-js-client
docs: clarify options prop requirement for Pages Router SSR with serverState
- Dominant language
- TypeScript
- Stars
- 67
- Forks
- 45
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 4
Description
## Description
### Problem
The current [Next.js Pages Router SSR documentation](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/nextjs-and-ssr) 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:
```tsx
// From react.tsx type definition
options?: Parameters[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:
```tsx
```
**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`
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.