92ada0ad22
* feat: custom prompts * feat: settings improvements
4.5 KiB
4.5 KiB
Initial State Hydration Refactor (LLD)
Goal
Eliminate per-component initial* props by creating the Zustand store with preloaded data at the layout/route boundary, so SSR content renders immediately without post-hydration flashes.
Current Behavior
StateProvideris inapp/layout.tsxand always instantiates the store without initial data.StateHydratorinjects server data viauseEffect, which runs after first paint.- Pages pass
initial*props to avoid empty SSR output.
Proposed Architecture (Settings)
1) Introduce a Settings Store Provider
Create layout-level client providers that accept initialState and create the store once:
apps/web/components/state-provider.tsx- keep existing
StateProviderAPI but allowinitialStateto be passed.
- keep existing
- new
SettingsStateProvider(or reuseStateProviderdirectly in settings layout) that acceptsinitialStateand wraps settings pages.
2) Move Store Creation From Root Layout (Settings Only)
- Root
app/layout.tsxshould no longer create the store (or should accept and pass an initial state when available). - For sections that need SSR data, create the store in their layout and pass
initialState.
3) Replace StateHydrator With Initial Store Creation
- For sections using SSR data, remove
StateHydratorfrom those layouts/pages. - Create the store with
createAppStore(initialState)at layout render time.
4) Update Settings Layout (Fix Sidebar Flash)
apps/web/app/settings/layout.tsx- Build
initialStateexactly as today. - Wrap children with
<StateProvider initialState={initialState}>(or newSettingsStateProvider). - Remove
<StateHydrator>usage. - Sidebar fix: The sidebar reads from
settingsAgents,workspaces, etc. With a settings-level provider created from server data, the sidebar will render populated on first paint (no post-load flash).
- Build
5) Update Pages Under Settings
- Remove
initial*props that were only used to avoid flash. - Components should read from store only (via hooks) and use store
loadedflags. - Example:
PromptsSettingsshould read prompts from store, noinitialPromptsprop.
6) Decide Provider Boundaries
Two options:
- Option A (Scoped provider): Settings layout creates its own store instance. Pros: isolates settings state. Cons: state is not shared with other routes.
- Option B (Shared store): Root provider accepts initial state per route (requires root layout to receive data, which Next.js does not support directly). Practically hard with App Router.
Recommendation: Option A (Scoped provider) per section (e.g., Settings), so SSR data is injected at first render without a flash.
Detailed Steps
- State Provider Changes
- Update
StateProviderto acceptinitialState?: Partial<AppState>(already in types). - Ensure it uses
useState(() => createAppStore(initialState))(already does).
- Update
- Settings Layout
- Replace
StateHydratorwithStateProviderwrappingSettingsLayoutClient. - Remove provider from root layout only if it conflicts. Otherwise, nest a provider for settings only.
- Replace
- Settings Layout Client
- If nested provider is used, ensure
SettingsLayoutClientuses the nearest provider.
- If nested provider is used, ensure
- Pages/Components Cleanup
- Remove
initial*props (e.g.,initialPrompts,initialEditors, etc.). - Update hooks/components to rely on store state.
- Remove
- Hooks
- Keep hooks as-is but remove special-casing for initial props.
- SSR Validation
- Verify that settings pages render with data on first paint.
- Remove
StateHydratorusages where the new provider is used.
Migration Plan (Settings Focus)
- Implement provider shift for Settings only.
- Remove
StateHydratorfromapps/web/app/settings/layout.tsxand create the store withinitialState. - Ensure Settings sidebar uses the settings-level store (no data flash).
- Update settings pages (prompts/editors/notifications) to remove initial props if desired.
- Add regression checks for settings pages to ensure no blank state on first render.
- Optionally expand to other sections later.
Risks
- Nested providers create isolated state between main app and settings pages.
- Multiple store instances may impact shared data expectations (e.g., websockets updating a different store).
- Must ensure WS connector uses the correct store instance or remains in root if necessary.
Acceptance Criteria
- Settings pages render data immediately without post-load flash.
- Components do not require
initial*props to render lists. - No runtime errors due to missing provider context.