$ 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
});