a2ui-project / a2ui-project/a2ui
A2uiSurface throws on SSR: useSyncExternalStore missing getServerSnapshot
- Vorherrschende Sprache
- TypeScript
- Sterne
- 16.4k
- Forks
- 1.3k
- Ø Merge
- 3 T. 15 Std.
- Gemergte PRs (30 T.)
- 134
Beschreibung
## Bug
When rendering `` in a server-rendered React app (Next.js App Router, Remix, etc.), React throws during the server pass:
```
Error: Missing getServerSnapshot, which is required for server-rendered content. Will revert to client rendering.
```
Tracked this down to `A2uiSurface` calling `useSyncExternalStore` without a `getServerSnapshot` argument. React requires this on the server to produce a stable, hydration-safe snapshot — without it the call throws on every SSR render.
## Steps to reproduce
1. Install `@a2ui/react@0.10.2` in a Next.js 14+ (App Router) project
2. Render `` anywhere that executes server-side
3. Server logs the above error on first render
## Expected vs actual
Expected: the component either renders gracefully on the server (returning a stable snapshot or `null`) or is documented as client-only with a clear pattern for opting out of SSR.
Actual: React throws during the server render pass. In strict SSR setups (e.g. `experimental.serverActions: true` or a CI render test) this surfaces as a hard error rather than a recoverable warning.
## Workaround
Skip the component server-side via a `useEffect`-guarded mount flag or a `dangerouslySetInnerHTML` fallback. Works, but means the surface is effectively non-functional until JS loads.
## Environment
- `@a2ui/react`: 0.10.2
- `react`: 19.x
- Next.js: 14 (App Router)
Beitragsleitfaden
Rechercherichtung
Finde die A2uiSurface-Komponente in der Codebase, wahrscheinlich in einer Datei wie `packages/react/src/A2uiSurface.tsx`. Suche nach dem `useSyncExternalStore`-Aufruf. Verstehe die React 19 SSR-Anforderungen für `getServerSnapshot`. Prüfe, ob es im Projekt bestehende Patterns für server-side rendering gibt. Der Fix besteht darin, eine passende `getServerSnapshot`-Funktion bereitzustellen oder die Komponente client-only zu machen. Verifiziere den Fix durch Tests in einem Next.js App Router-Setup.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- next.js, react, typescript
- Bereich
- frontend
- Issue-Typ
- Bug
- Schwierigkeit
- 3/5
- Geschätzter Aufwand
- 1-2 Tage
- Aktivitätsstatus
- Ruhig
- Klarheit
- Klar beschrieben
- Anfängerfreundlichkeit
- 55/100