Qwik City routeLoader$ data and qwik-react islands: shared state serialization limits

Answer

Confirmed facts

• routeLoader$ runs on the server and its return value is serialized into the initial HTML so the client can resume without refetching.
• Only values that Qwik’s built‑in serializer can represent survive this trip: plain objects, arrays, strings, numbers, booleans, null, plus Date, URL, Map, Set, and Error subclasses (as of Qwik 1.x).
• qwik‑react islands hydrate as normal React; props passed into a qwikify$'d component must be plain JSON‑serializable data because React recreates the component tree from serialized props and does not share Qwik’s resumable state graph.
• Class instances, functions, closures, Promises, and live store references cannot cross into a React island; they are dropped or cause errors.
• There is no officially supported pattern for wrapping non‑serializable objects in a behavior‑preserving proxy that works across the Qwik‑to‑React boundary.
• For chunk loading, the optimizer treats routeLoader$ data as part of the initial serialized state (no extra chunk); the React island’s JavaScript is a separate eagerly loaded bundle, so loader data does not influence prefetch decisions.

Likely explanation / practical steps

1. In your routeLoader$, return only plain‑serializable data. If you have a class instance, convert it to a plain object (e.g., { id: instance.id, name: instance.name }).
2. Pass that return value directly to the qwikify$'d component: const data = await routeLoader$(); then where the island is created with qwikify$(MyReactComponent).
3. Inside the React island, treat the props as immutable input. If you need behavior (methods) that belonged to the original class, reconstruct them locally from the plain data (e.g., create a helper function or use a React hook).
4. Avoid trying to pass a Qwik signal or store directly; instead, expose only the serializable slice you need.
5. If you suspect the serializer is dropping something, check the rendered HTML: the loader data appears inside __QWIK_STATE__ script, while React props are embedded as plain JSON attributes.

Missing diagnostic detail

To confirm which built‑in types are serializable in your setup, please let us know the exact version of @builder.io/qwik you are using (e.g., 1.2.3). The serializer’s support for types like Map, Set, or BigInt can vary between releases.