Qwik City Loader Serialization Limits

Qwik City loader serialization limits for non-JSON types

0 reputation · 11 Mar 2020, 02:57 UTC

41.1K views0

Loader Data Serialization

Qwik City requires route loader functions to return data that is JSON-serializable to ensure correct hydration on the client. This constraint is fundamental to the framework's resumability model, as the state must be transferred from the server to the browser.

Serialization Behavior

While the official documentation emphasizes plain JSON-serializable values, there is ambiguity regarding the handling of complex types such as Date, Map, and Set. The internal serialization process may omit unsupported types or trigger warnings, but the exact behavior is not defined as a stable public API.

Currently, developers must manually transform these types into serializable formats before returning them from the loader to ensure consistent behavior across different environments.

Does the Qwik runtime provide a mechanism to automatically handle non-JSON types in loaders?
Will future versions enforce stricter validation on loader return types, and if so, how will this impact backward compatibility?

Keep exploring this topic

Qwik useStore serialization boundaries for non-POJO state

An inquiry into the serialization constraints of Qwik's useStore when handling non-POJO data across the server-client boundary in production builds.

Qwik resumability serialization change for non-serializable class instances

Qwik's resumability architecture serializes state into HTML, but non-serializable class instances create a compatibility boundary during client-side de-serialization in Qwik 1.x.

Does useResource$ re-fetch data when a lazily hydrated Qwik component resumes on the client?

When a server-rendered Qwik component using useResource$ lazily resumes on the client, does the resource re-fetch, and is an explicit cache key required to avoid duplicate requests?

Qwik signal-driven alerts: scoping updates without notification noise

Designing alert state in Qwik so signal updates reach only subscribed regions: collection vs scoped signals, server-driven payloads, and subscription cleanup.

A critical detail regarding Qwik City's resumability is that loader serialization relies on JSON.stringify. Because Date, Map, and Set are not natively supported by the JSON spec, they are typically omitted or converted to undefined during the transfer from server to client.

Practical Transformation Patterns

To ensure data consistency and avoid hydration mismatches, these types must be manually transformed before the loader returns. Common patterns include:

Dates: Use date.toISOString() to pass a string that can be reconstructed via new Date(isoString) on the client.
Maps: Convert to a plain object using Object.fromEntries(map) or an array of pairs via Array.from(map.entries()).
Sets: Convert to an array using Array.from(set).

Developers can verify this behavior in development mode by returning a Map from a loader; the client-side state will typically lack the property, often accompanied by a console warning.

Qwik City loader serialization limits for non-JSON types

Loader Data Serialization

Serialization Behavior

0 answers

Your perspective belongs here.

1 question comment

Practical Transformation Patterns