Qwik City Route Loader Serialization Limit for Client Data

Direct Answers

Serialization errors are thrown, not silently omitted. When a route loader returns a value that JSON.stringify cannot serialize (functions, class instances, streams, circular references, etc.), Qwik City throws during the server render pass. The request fails with a 500 response and a server-side stack trace pointing to the serialization call site.

No documented size or depth limits exist in Qwik City itself. The practical ceiling is the maximum HTML response size your hosting platform or browser will accept, because the entire loader state is inlined as a JSON string inside a <script type="qwik/json"> tag in the rendered HTML.

SSR vs SSG changes when the failure appears, not whether it appears. With on-demand SSR the error occurs at request time (500 for that request). With SSG the same error occurs at build time and fails the entire build, preventing deployment. Adapter choice (Vercel, Netlify, Cloudflare Pages, Node, etc.) does not alter this behavior; it only changes where the SSR request or SSG build executes.

Confirmed Behavior

• Qwik City uses JSON.stringify internally to embed loader data into the HTML payload.
• useLoaderData retrieves the already-deserialized data from the client-side Qwik store; it never re-runs the loader. Re-execution only happens on explicit navigation or when the loader key changes.
• Date objects serialize as ISO strings and arrive on the client as strings; you must parse them back to Date objects in the consuming component.
• Circular references in the loader return value will cause JSON.stringify to throw; ensure the object graph is acyclic or supply a custom replacer.

Practical Implications

• Large loader payloads increase HTML size and Time-to-First-Byte. Consider pagination, projection, or moving heavy data to a separate client-fetched API endpoint.
• If you rely on SSG, a single unserializable loader return value breaks the whole build. Add a CI step that runs static generation (npm run build) to catch this early.
• Streaming SSR (when enabled) still requires the loader to complete and serialize before the shell can be flushed; the loader itself cannot stream its return value.

Verification Steps

1. Create a minimal Qwik City project: npm create qwik@latest.
2. Add a route loader that returns a non-serializable value (e.g., export const onGet = () => ({ fn: () => {} })).
3. Run npm run dev and request the page to observe the 500 error and server console stack trace.
4. Run npm run build with the same loader to confirm the build fails at the static generation step.
5. Return a large object (e.g., 5 MB of JSON) from a loader, build/deploy, and inspect the network payload to verify the full JSON is inlined in the HTML.