$ Boundaries

Rules

  • Only serializable data can cross a $ boundary.

Serialization Boundary

A serialization boundary occurs whenever you cross a lexical scope of a function that is converted into lazy loadable form. It is always denoted by $(...) (or ____$(...)) See example:

import { component$ } from '@builder.io/qwik';
 
export const topLevel = Promise.resolve('nonserializable data');
 
export class MyCustomClass {
  val: string;
 
  constructor(val: string) {
    this.val = val;
  }
}
 
export const Greeter = component$(() => {
  // BEGIN component serialization boundary
 
  // Referring to top level symbols that are exported is always allowed.
  console.log(topLevel); // OK
 
  const captureSerializable = 'serializable data';
  const capturePromise = Promise.resolve('Qwik serializes promises');
  // Instances of custom classes are not serializable.
  const captureNonSerializable = new MyCustomClass('non serializable');
 
  return (
    <button
      onClick$={() => {
        // BEGIN onClick serialization boundary
 
        // Referring to top level symbols that are exported is always allowed,
        // even if the value is non-serializable.
        console.log(topLevel); // OK
 
        // Capturing a non-top-level variable is allowed only if:
        // - declared as `const`
        // - is serializable (runtime error)
        console.log(captureSerializable); // OK
        console.log(capturePromise); // OK
 
        // Referring to captureNonSerializable will pass static analysis but
        // will fail at runtime because Qwik does not know how to serialize it.
        console.log(captureNonSerializable); // RUNTIME ERROR
 
        // END onClick serialization boundary
      }}
    >
      click
    </button>
  );
  // END component serialization boundary
});

Contributors

Thanks to all the contributors who have helped make this documentation better!

  • fabien0102
  • wuweiweiwu
  • manucorporat
  • adamdbradley
  • voluntadpear
  • mrhoodz
  • hamatoyogi