Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

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

Aperta
  • Qualcosa non va?
#371 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
55/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Ferma
Stack tecnologico
next.js, typescript
Ambito
documentation

Direzione di ricerca

Inizia dalla documentazione di Pages Router SSR all’URL collegato, quindi leggi le righe 8-13 e 35-54 di react.tsx per confermare il contratto di inizializzazione di FlagsmithProvider. Aggiorna l’esempio e la nota esplicativa in modo da coprire serverState, la prop options, preventFetch e la conseguenza di manual-init; il completamento è definito dai criteri di accettazione elencati.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

enhancement good first issue

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
Lingua principale
TypeScript
Stelle
67
Fork
47
Merge medio
2h 26m
PR unite (30g)
2

Preparare l'ambiente

  • Nessun Dockerfile né file Docker Compose
  • Ha un modello di pull request
  • Nessuna guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Flagsmith/flagsmith-js-client

Tutte le issue di Flagsmith/flagsmith-js-client

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.