Reference

Semantics

The semantics contract, version 1: what every target guarantees, from setup and state to events and rendering, and the corpus case that checks each rule.

Vue's semantics are the reference wherever every target can meet them. Where a target cannot, the contract states the guarantee that every target keeps, and the capability matrix declares the difference. Each rule has corpus cases that the tests run on all seven targets: the server's HTML, the DOM, the accessibility tree, the pixels and the trace of every interaction must match Vue's.

This is version 1, as milestone M2 built it, with the models and context rules of M3, composition, and the rules for composables and shared modules.

RuleGuaranteeCases
Setup runs onceThe setup runs once per instance; a const keeps its first valuesemantics/setup-once, semantics/props-seed-state, semantics/props-seed-let, semantics/helper-order
Reactive propsThe template, getters and client code read a prop's current valuesemantics/reactive-props, semantics/derived-from-props, semantics/late-optional-prop
Read after writeA read of state after a write in client code sees the new valuesemantics/read-after-write, semantics/nested-call-bubbling
Deferred readsCode that runs later reads the latest state and propssemantics/deferred-reads, events/listener-pairs
Derived consistencyA computed read right after a write of what it reads is up to datesemantics/derived-consistency
WatchersA watcher calls back once per run of client code, on a change, with the previous valuesemantics/watch-timing, effects/watch-identity, effects/async-watchers, effects/async-overlap
Effects are client-onlyNo effect and no hook changes what the server renderssemantics/effects-client-only
watchEffectwatchEffect runs after the first render, and after a change of what it readseffects/watch-effect, effects/persistence-and-fetch
TeardownEvery cleanup runs before the onUnmounted hookslifecycle/teardown-order
nextTickawait nextTick() resumes once the DOM shows the writes before itlifecycle/next-tick, effects/pre-and-post
Emitemit returns nothing, and its listeners may run latersemantics/emit
EventsA listener hears the DOM's event of its name, with its optionsevents/form-events, events/event-options, events/listener-order, events/focus-and-change
Keyed listsA keyed item keeps its element and typed text while its list reorders or replaces it, and its focus where it keeps its placesemantics/keyed-lists, control-flow/keyed-reorder-focus
DeterminismRendering is a pure function of props and statediagnostics/nondeterministic-render
Prevent defaultpreventDefault() and stopPropagation() act while the event is dispatchedsemantics/prevent-default, events/guard-controls, events/keyboard-navigation
ModelsA bound model shows its parent's value, and an unbound one keeps local statesemantics/models, models/component, models/several
Contextinject gives the nearest provider's value, or its fallback, and follows a provided refcontext/static, context/fallback, context/reactive, context/nested
ComposablesA call runs the composable's setup once, where the call sits, with its own statecomposables/use-toggle, composables/use-media-query
ArgumentsA value is read once, a getter reactively, and a callback is called from client codecomposables/getter-argument, composables/callback-argument, composables/use-controllable-state
Read after write, acrossClient code that calls a composable's function reads its write right aftersemantics/composable-read-after-write
Effect order, acrossA composable's watchers and hooks run where its call sits among the caller's ownsemantics/composable-effect-order
Teardown, acrossA composable's unmount hooks run when its caller unmounts, once for each callsemantics/composable-unmount-order
Shared modulesA module's values are read-only, and the same in every target's outputmodules/shared-constants, modules/shared-helpers, modules/module-constants, modules/nested-modules
HydrationA server render hydrates to the client's DOM, keeps its ids, and stays interactivehydration/use-id, hydration/props-render, hydration/interactive
Raw HTMLinnerHTML renders its markup as written, unescaped and unsanitised, and replaces it when it changesjsx/raw-html, jsx/raw-html-update, jsx/raw-html-list
Teleport<Teleport to> mounts its one element at the end of to once the component has mounted, renders none of it on the server, and removes it with the componentteleport/basic, teleport/dialog, teleport/siblings, teleport/root
DirectivesA directive's hooks run in the browser only: mounted once its element is in the DOM, updated after a render that changes its value, unmounted once the element leaves, a descendant's before its ancestor'sdirectives/order, directives/updated-value, directives/shared, directives/focus-trap, directives/click-outside
Transition<Transition> runs Vue's enter and leave classes on its element, keeps a leaving element in its place until its leave ends, and renders the settled child on the servertransitions/leave, transitions/swap, transitions/enter, transitions/appear, transitions/outer, transitions/directive, transitions/reverse, transitions/nested
Async setupThe server renders what an async setup awaited, a client mount renders once it resolves, and after hydration the setup runs again while the server's DOM staysasync-setup/resolved, async-setup/props, async-setup/chained, async-setup/nested, async-setup/rerun, async-setup/provide, async-setup/rows

The cases are in tests/integration/cases.

Setup runs once

The setup runs once per instance on every target. A const is evaluated once and keeps its first value, so one that reads a prop does not follow it (UF2007 warns). State seeded from a prop, ref(initial), starts with the prop's value at creation and keeps its own value when the prop changes.

  • React runs the component's body on every render. A constant that reads the component's values is a useState whose initial value React reads once, and one that reads nothing moves to the module. A state's initial value that calls or constructs is passed as a function, useState(() => …), so that React evaluates it once.
  • Svelte and Solid read a prop or a state in the setup through untrack.
  • Angular sets an input after it constructs the class, so a field initialiser would read an optional input's default, and throw for a required one. State seeded from an input is a linkedSignal, and a constant that reads one a computed, each read once in ngOnInit, after the inputs are set, through untracked. A setup let seeded from an input is assigned there too, in source order. A function passed as a value is an arrow field, declared before the setup's state, derived values and constants, so an initial value can call it.
  • Qwik runs the component's body again when a signal it reads changes, and its optimiser reads a destructured prop as the current prop. So a constant that reads a prop, a state or a derived value is a useConstant. useSignal reads its initial value once. Qwik keeps the watchers and hooks in source order, and moves up a declaration that one of them reads before the source declares it.
  • Astro renders each request as a new instance, so state never survives a new render there. A test that checks state across a rerender declares that it requires interactivity, which Astro does not support.

Qwik's useConstant evaluates its function again while the value is null or undefined: a constant whose first value is nullish follows what it reads until it holds a value.

Reactive props

A destructured prop read in the template, a computed, a watcher's getter or client code reads the prop's current value, on every target, as in M1. Read in the setup, ref(initial), it gives the value at creation (Setup runs once).

  • Solid reads every prop as props.name, and Angular as this.name().
  • React reads a prop that deferred code reads through a mirror (Deferred reads).
  • A watcher watches a prop through a getter, watch(() => celsius, …) (UF2020).

Qwik's useComputed$ and tasks follow only the props the parent passed when they first read them. So on Qwik a derived value or a watcher misses an optional prop that the parent passes only after the mount, through a spread that gains the key, though the template sees it (late-prop, a warning). Pass the prop from the start, undefined while it has no value.

Read after write

A read of state after a write, in client code, sees the new value: in the same function, in a function it calls, in another listener of the same event, after an await, and in code that runs later.

Tally.uf.tsx
function addTwice() {
  count.value++;
  count.value++;
  emit("total", count.value);
}

React's state changes only at its next render, so React keeps a mirror ref of every state that client code writes. It writes the mirror before each setter call, and every piece of client code reads the mirror; the template reads the state:

Tally.tsx
function addTwice() {
  countRef.current++;
  setCount(countRef.current);
  countRef.current++;
  setCount(countRef.current);
  onTotal?.(countRef.current);
}
  • Vue's and Svelte's state, Solid's signals, Angular's signals and Qwik's signals apply a write at once.
  • React writes ??=, ||= and &&= out, x = x ?? y, and a ++ of a local that a nested function captures as += 1, because the React Compiler bails out on both.
  • Qwik makes a local function that client code calls a $() function. A call of it that is a statement, or whose value is used, is awaited, so a read after the call sees its writes. Where a call must not wait, in a listener that another listener of the event follows or in a task, Qwik writes the function's statements in place. A call of a function that returns a promise is that promise, awaited only where the source awaits it.

Deferred reads

Code that runs later, after an await, in a timer's callback or in a callback a hook schedules, reads the latest state and props, never a render's snapshot.

DeleteFile.uf.tsx
async function requestDelete() {
  confirming.value = true;
  await new Promise<void>((resolve) => {
    resolveConfirmation = resolve;
  });
  confirming.value = false;
  emit("deleted", fileName, copies.value);
}

While the deletion waits for its confirmation, the user adds a copy and the parent renames the file. The continuation emits the new name and the new count, on every target. React's closure would hold the render's values, so React reads a prop and an event's listener that deferred code reads through mirrors, synced after every render:

DeleteFile.tsx
const fileNameRef = useRef(fileName);
const onDeletedRef = useRef(onDeleted);
useLayoutEffect(() => {
  fileNameRef.current = fileName;
  onDeletedRef.current = onDeleted;
});

const [copies, setCopies] = useState(1);
const copiesRef = useRef(copies);
const [confirming, setConfirming] = useState(false);
const confirmingRef = useRef(confirming);
const resolveConfirmation = useRef<(() => void) | undefined>(undefined);

async function requestDelete() {
  confirmingRef.current = true;
  setConfirming(confirmingRef.current);
  await new Promise<void>((resolve) => {
    resolveConfirmation.current = resolve;
  });
  confirmingRef.current = false;
  setConfirming(confirmingRef.current);
  onDeletedRef.current?.(fileNameRef.current, copiesRef.current);
}

The other targets read their props and state live: Vue's, Svelte's and Solid's props, Angular's input signals, and Qwik's props, which its optimiser reads from the props object.

A local function that client code passes as a value, to addEventListener or a timer, keeps one identity for the instance's life, so the listener one handler adds is the one another removes. React declares it once, useState(() => …), and it reads props and state through the mirrors. Qwik creates a component's $() functions again each time it renders, so it holds such a function in a useConstant.

Derived consistency

A computed read in client code right after a write of what it reads is up to date, on every target. React's useMemo gives the value of the last render, so client code reads a getter over the mirrors instead, currentTotal():

SeatPicker.tsx
const total = useMemo(() => seats * pricePerSeat, [seats, pricePerSeat]);

function currentTotal() {
  return seatsRef.current * pricePerSeat;
}

const summary = useMemo(
  () => (seats === 1 ? `1 seat for ${total}` : `${seats} seats for ${total}`),
  [seats, total],
);

function currentSummary() {
  return seatsRef.current === 1
    ? `1 seat for ${currentTotal()}`
    : `${seatsRef.current} seats for ${currentTotal()}`;
}

function addSeat() {
  seatsRef.current += 1;
  setSeats(seatsRef.current);
  onQuote?.(seatsRef.current, currentTotal(), currentSummary());
}
  • Vue's, Angular's and Svelte's derived values recompute when they are read. Solid's createMemo recomputes as each write is made, and Qwik's useComputed$ when what it reads is written.
  • React prints a useMemo only for a computed that the template, a getter, a watcher's source or watchEffect reads. One that only client code reads is its live getter alone.
  • React's useMemo and Solid's createMemo evaluate a getter when the component renders, even when no code reads it. So a getter gives a value for every state the component can reach, and reads only what is declared before it (UF2023).

Watchers

A watcher's callback runs after the writes that trigger it, before the interaction settles. It runs only when a source's value changed by Object.is (any element, for an array source): a value written away and back calls nothing back. Its previous is the source's value at the watcher's last callback, or at its creation; it is undefined on an immediate first run, and [] for an array source. Its onCleanup callbacks run right before its next callback and when the component is removed, never on a run that calls nothing back. A callback that awaits does not hold the watcher: a change while it waits runs its cleanups and calls back again at once.

Writes within one synchronous run of client code trigger a watcher once at most, whatever blocks, guards and loops the run holds. Writes separated by an await, or, on Qwik, by a call of a local function, may trigger it once or twice: code must not depend on whether they coalesce. await nextTick() always separates them. The order of different watchers that one run triggers is not part of the contract: Vue and Solid order them by trigger, Svelte and React by declaration. So the tests record each step's emits grouped by event, and check the order of emits only within one synchronous run.

  • Vue copies the watcher, and reads a state that holds an object or an array (a shallowRef) through a getter, watch(() => selected.value, …): Vue's watch calls a shallow ref's watcher back on every run, changed or not.
  • React runs each watcher in an effect over its source, with the previous value in a ref and the callback in an effect event. One handler's writes make one render, so the effect runs once. React has no phase before the render, so a watcher without flush: "post" is an effect after it too: where one writes state, the post watchers and watchEffect wait until what it wrote has rendered, as Vue runs them after its pre watchers' writes.
  • Svelte's $effect.pre runs once after a synchronous run, and compares with Object.is.
  • Solid runs what a write triggers as the write is made, so a watcher goes through createWatcher, a scheduler as Vue's: createReaction queues the watcher when a value it read is written, and a microtask queued at the first write runs each queued watcher once, those before the DOM updates first, comparing with Object.is. Client code is copied as written, with no batch. watchEffect goes through createWatchEffect, over the values it reads. Writes made while Solid mounts the component, such as an immediate watcher's during the setup, call the watchers back after the onMounted hooks, where Vue calls them before.
  • Angular's effects run in its change detection, once for one handler's writes, over a computed of the source.
  • Qwik's useTask$ runs once for one handler's writes; a call of a local function is a lazy call that Qwik awaits, so writes on each side of it may call back twice. An async callback's body goes on by itself, void (async () => {…})(): Qwik runs a task again only once its last run has settled.

Effects are client-only

No watcher without immediate, no watchEffect and no lifecycle hook runs during the server's render, and no effect changes what the server renders. An immediate watcher's first callback runs during the setup on Vue, on the server too, and may on Qwik, so it is held to what the server can run (UF2013).

  • Vue writes watchPostEffect for watchEffect. A watcher without immediate, a post effect and the hooks never run in Vue's server setup.
  • Svelte writes $effect and onMount, and never onDestroy, which its server runs.
  • Solid writes onUnmounted as onMount(() => onCleanup(…)): a plain onCleanup runs when the server disposes its render.
  • Angular writes afterNextRender and afterRenderEffect, which never run on the server, creates watchers in ngOnInit with their immediate callback behind a browser check, and runs onUnmounted in ngOnDestroy, behind a browser check too: Angular destroys a component on the server after it renders.
  • Qwik writes useVisibleTask$, which runs in the browser only, for hooks, watchEffect and post watchers. Once Qwik resumes a server-rendered page, it runs a task again only when a value it tracks changes, so an immediate watcher's first callback has then run on the server only. The tests don't check resuming yet.

watchEffect

watchEffect runs after the first render, and again after any prop, state or derived value it read changes. It runs after the DOM updates on every target. Its dependencies are the reactive values it reads in the straight-line start of its body (UF2015): React, Solid and Qwik list them before the effect runs, where Vue tracks what each run reads. What it hands on to run later, a timer's callback, a promise's continuation, a listener or an onCleanup callback, is no dependency on any target. A DOM read in a watcher needs flush: "post" (UF2018); watchEffect needs nothing. An effect that writes a state it reads while it runs would run itself again on every target but Vue (UF2027).

  • Qwik may run a visible task twice for one change, so its watchEffect keeps the values it last ran for, and runs only when one changed by Object.is.
  • React's watchEffect waits, as a post watcher does, until what the pre watchers wrote has rendered, and then runs only with values its last run did not have.

Teardown

When a component is removed, every watcher's and watchEffect's cleanups run first, then the onUnmounted hooks, in source order, on every target: Vue stops a component's effects before it calls its hooks. The order among the cleanups of different watchers is not part of the contract.

  • React declares the onUnmounted effects after every other effect, and React tears effects down in declaration order.
  • Svelte prints an onUnmounted hook declared before a watcher with a cleanup after it.
  • Solid disposes a component's computations in the reverse of their creation, so it writes the hooks before the first watcher, in reverse order: they run after every cleanup, in their order.
  • Angular destroys the watchers and the effects that register a cleanup in ngOnDestroy, then runs the hooks.
  • Qwik registers the hooks' visible tasks after every other task.

Teardown code reads no template ref, and does not wait (UF2026): Vue and React empty a ref before it runs, and Vue drops an emit once the component is unmounted.

nextTick

await nextTick() resumes once the DOM shows the writes made before it, and what the watchers they trigger write. A pending nextTick() resolves when its component is removed too.

  • Vue writes nextTick, and Svelte tick.
  • Solid applies a write to the DOM as it makes it, and its watchers run in a microtask queued at the first write, so its nextTick helper resolves a promise after them.
  • React's useNextTick asks for a render of its own and resolves once React has rendered it, run its effects, and rendered what the component's watchers wrote.
  • Angular's nextTick method renders the pending change itself in a microtask, ApplicationRef.tick(), and resolves after it.
  • Qwik renders in a microtask, so its nextTick helper resolves after the next task.

On Vue, Svelte, Solid and Angular the code after await nextTick() runs in the task that wrote, before the next event. React and Qwik may resume in a later task (Outside the contract).

Emit

emit returns nothing, and code never depends on a listener having run: Qwik's listeners are lazy functions that may run after the emit. So an emit is a statement of its own (UF2017). Within one synchronous run, a component's emits reach the listeners in order.

Code emits nothing once its component is removed: Vue drops such an emit, Angular drops it with a warning, and the other targets deliver it. Angular destroys a watcher and a watchEffect in ngOnDestroy, before it stops the outputs, so that a cleanup that emits reaches its listener there as on Vue.

Events

A listener hears the DOM's event of its name, with its option (Events): change on a text field when it commits, focus and blur without bubbling, a capture listener before the target's and a bubble listener after, a once listener once for each element, and a passive listener without preventDefault() (UF3034). The listeners of one event and phase on one element run in attribute order.

  • React listens natively where its synthetic event differs from the DOM's, and keeps once with a guard (event-semantics and event-once, emulated). It runs an element's listeners of one event and phase in one handler, in attribute order; an async one is called and left to finish, so every later one starts in the dispatch.
  • Svelte runs a once listener's handler through an inline guard, once, set when the handler first runs, so an event that a descendant stopped does not use it up (event-once, emulated).
  • Solid listens natively to an event it would delegate when the component also listens to it natively, with once or passive or a handler typed as the DOM types the event, so the two run in the DOM's order. An element with several listeners of one event and phase adds them all from its ref callback, in attribute order.
  • Angular keeps the options through attribute directives (emulated). Where an element has several bubble listeners of one event, they are one template listener that chains their statements in attribute order, a once one behind a guard, once(clickOnce, $event) && ….
  • Qwik runs a capture listener from the window when an element of the component listens to the same event in both phases. Such a listener's preventDefault() or stopPropagation() cannot run at its element's place, so Qwik reports it (conditional-event-control). Where the component also listens to an event without passive, Qwik's passive listener of that event is not passive: Qwik's loader runs passive and other handlers in two passes over the path. An element's listeners of one event are one handler that runs them in order, and a listener that another listener of the event follows writes its calls of local functions in place, so it is done when the next one starts.

Keyed lists

A list's key names its item's element. While the list reorders, and while an item is replaced by a new object of the same key, the item keeps its element, and so what the element holds: its typed text, a ticked box and, where it keeps its place, its focus. The element follows the latest item. A new key gets a new element, and an element whose key is gone is removed.

A browser blurs an element that is moved in the document, and each framework picks which elements it moves to reorder a list. So the focus stays where the focused element keeps its place and the rows around it move, and where its item is replaced in place. React puts the focus back on an element it moved, and the other targets don't. An element that is moved itself keeps its typed text, but may lose its focus (see Outside the contract).

Checklist.uf.tsx
{entries.map((entry) => (
  <li key={entry.id}>
    <label>
      {entry.label}
      <input name={`note-${entry.id}`} aria-label={`Note for ${entry.label}`} />
    </label>
  </li>
))}
  • React, Vue, Svelte, Angular and Qwik key the element by the source's key: key, :key, {#each … (key)}, track and key again.
  • Solid's <For> follows the items themselves, so a list goes through an inline helper, KeyedFor, whose rows follow the key. A row is an object of getters named as the item, which TypeScript narrows as it narrows a prop: entry.value and entry.index.
Checklist.tsx
<KeyedFor each={props.entries} by={(entry) => entry.id}>
  {(entry) => (
    <li>
      <label>
        {entry.value.label}
        <input name={`note-${entry.value.id}`} aria-label={`Note for ${entry.value.label}`} />
      </label>
    </li>
  )}
</KeyedFor>
  • Astro renders a list once on the server, so nothing reorders it. A test that reorders or replaces a list's items requires keyed-identity, and is skipped there.

A conditional that switches branches replaces the branch's elements on every target, so focus and what was typed leave with them (semantics/nested-branches, state/narrowed-reads). React would reuse an element of the same tag in the same place. So where a branch holds state a user can change, a control, a link, a listener or a template ref, and two branches can render an element of one tag at their top, React keys every branch:

DeleteFile.tsx
{confirming ? (
  <button key={0} type="button" onClick={confirmDelete}>
    Confirm the deletion
  </button>
) : (
  <button key={1} type="button" onClick={requestDelete}>
    Delete
  </button>
)}

Determinism

Rendering is a pure function of props and state: a template, a getter, an initial value and the functions they call read no clock, no chance and no locale (UF3019), change nothing (UF3021, UF2011) and call only pure local functions (UF2014). A value from the clock or the machine is passed in as a prop, or written to state from client code.

Prevent default

preventDefault() and stopPropagation() act while the browser dispatches the event, on every target. A call after an await, or in code the handler hands on, such as a timer's callback, comes too late on every target (UF3033). Every other call acts where it stands: under a test, in a switch case, beside other statements or after a guard clause. The tests fail a form submission or a link's navigation that a component does not prevent.

Qwik runs a handler after the event, so it runs the calls apart, while the event is dispatched (Events). A call at the top of a listener, on every event, is a preventdefault: or stoppropagation: attribute. A call there under a test of the event alone, or after guard clauses on the event, runs in a sync$ handler before the listener's own. Qwik cannot run any other call at dispatch, and reports it (conditional-event-control, an error): events/keyboard-navigation has no Qwik output.

Models

A model is controllable on every target. Bound with v-model:<name>, the child shows its parent's value, and a write in the child asks the parent to change it: the parent's state changes, and so does what the child shows. Unbound, the child keeps the value as local state, which starts at the model's default and which no write of the parent's reaches (Models).

  • Vue writes defineModel, Svelte a $bindable prop and Angular model(), which tell the two apart by themselves.
  • React, Solid and Qwik give a model a value prop and a callback, and keep local state while the value prop is undefined. So a model bound to undefined acts unbound there (Outside the contract).
  • Astro renders the model's value, from the parent or the default, and nothing writes it.

v-model on a form control binds its state on every target: the text, the checked state, the selected options. A text field updates its ref on input events, and the modifiers trim, lazy and number do what Vue's do.

Context

inject(key, fallback) gives the value of the nearest ancestor that provides the key, or the fallback where none does. A component that injects a key and provides it too reads its parent's value. An injected value is read-only (UF2034). A provided ref or computed stays reactive: a descendant that reads it renders each change.

  • Vue provides a ref itself, and Qwik its signal. React, Svelte, Angular and Solid provide an object with a value getter over the state, refObject (reactive-context). React makes it again at each render of the provider, so its deferred code reads the value of the last render (Outside the contract).
  • Angular injects from the parent's injector, with skipSelf, so a component's own providers never answer its own inject.
  • Astro renders each component on its own, so inject gives its fallback there (context, a warning).

Composables

A call of a composable runs the composable's setup once, where the call sits in the caller's setup, so it runs once per instance, as the setup does (Setup runs once). Each call holds its own state: two calls in one component share nothing (composables/use-media-query destructures two under other names).

  • React's composable is a custom hook, which runs on every render, as the component's body does. Its state is useState, read once, so the call still holds one state per instance.
  • Svelte's caller keeps the object the composable returns, toggle.on, since runes don't survive destructuring.
  • Angular calls the composable from a field initialiser, in the component's injection context, or from ngOnInit through runInInjectionContext where an argument reads an input.
  • Astro's composable returns the initial values, and drops the client code.

Arguments

A value argument is read once, when the call runs: one that reads a prop or state is UF2007, and the composable keeps the value it had when the setup ran. A getter, () => price, follows the prop or the state it reads in every derived value and watcher of the composable. A callback runs in the caller's scope when the composable's client code calls it, and may write the caller's state and emit.

  • Qwik passes a getter as a useComputed$, and a callback as a QRL.

Read after write, across

A read of a returned ref or derived value after a call of a returned function, in the caller's client code, sees the function's writes, as the caller's own state does (Read after write).

  • React's hook returns a live reader for each state and derived value, currentItems beside items, and the caller's client code reads it, so it sees the hook's latest write rather than the last render's.

Effect order, across

A composable's watchers and hooks take the call's place among the caller's own, in source order: a mounted hook declared before the call runs before the composable's, and one declared after it runs after.

  • React and Solid declare composable-effect-order unsupported, for information (UF4005): React reorders a component's effects, and Solid queues a composable's watchers in its own module.
  • On Astro the cell is inert, like its other client-only cells: no effect runs there.

Teardown, across

A composable's onUnmounted hooks run when the component that called it unmounts, never before, and only for that instance: each instance's teardown follows its own unmount, in the order the instances go. The order of a composable's teardown among the caller's own is that of effect order, so it holds where composable-effect-order does.

Shared modules

A component reads a .ts module's values and its own module's constants as written, in its template, its setup and its client code (Shared modules). They are read-only, so every target reads one value, and each output tree holds the .ts modules unchanged.

  • Angular exposes a module value its template reads through a protected readonly member.
  • Qwik captures it as a module-level import, which a $ scope may read.

Hydration

A server render hydrates in the browser to the DOM the client renders: the framework reports no mismatch, every id is the one the server wrote, and the page responds to the first action, as a client render does. The tests check it on every case, on React, Vue, Svelte, Solid and Angular (L12). Each target keeps it its own way:

  • React renders the component as the root of the server's tree, as hydrateRoot hydrates it, so useId makes the same ids on both sides.
  • Angular counts ids per application, so the server and the browser each start at the same number.
  • Solid's ids match under hydration: its server and its browser count them from the same hydration key.
  • A <textarea> bound with v-model puts its caret after its text once it hydrates, as a client render leaves it, on every target that hydrates.
  • Qwik resumes the server's page instead of hydrating it. It runs no render, keeps no state for a component without client code, and runs visible tasks once its loader sees them, so the tests don't check a resumed page against a client render yet.
  • Astro runs nothing in the browser, so nothing hydrates.

Raw HTML

innerHTML={markup} sets an element's content to what the browser parses from the markup, on the server and in the browser alike. No target escapes or sanitises it, so the compiler warns at every use (UF3051): render only markup you trust.

When the string changes, the element's content is replaced. The element has no children of its own (UF3052), and its value is a string. Two targets need more than their own form:

  • Angular sanitises a bound innerHTML, which would drop id, data-* and style attributes, form controls and SVG. The markup goes through an inline pure pipe, TrustedHtmlPipe, which marks it trusted, so it renders as written there too.
  • Qwik's server writes an empty string as an attribute, so the markup is passed as markup || undefined, which renders an empty element.

Teleport

<Teleport to="body"> holds one element (UF3054), and to is a static CSS selector (UF3053). No target renders the element on the server, so hydration finds nothing in its place. Once the component has mounted, the element is appended to the element to selects, after what that element holds: it is the last element child of to. One component's teleports mount in source order.

The element unmounts with its component, or when a condition around the <Teleport> turns false, and nothing is left in to. It stays where it mounted while the list rows or the components that teleported it reorder, and a teleport filled into a child's slot mounts only while the child renders the slot. Its listeners, its state and its styles are the component's, wherever it mounts.

Astro runs nothing in the page, so it renders none of it (teleport, for information).

Directives

A directive is a behaviour an element takes, v-focus-trap={open.value}, declared once with defineDirective (UF2037). Its hooks run in the browser only, never during the server's render, so the server's HTML holds nothing a hook writes and hydration compares nothing of it.

mounted runs once per element, once the element is in the DOM, after the first render or after the server's HTML hydrates, with that render's value. updated runs after a render in which the value changed, as Object.is compares it, with the new value and the previous one, and never after a render that leaves the value the same. unmounted runs once, after mounted, when the element leaves the DOM or its component unmounts, and the element may already be detached.

Within one render, every unmounted runs before any mounted, so a branch that replaces another mounts after the other unmounts, and a descendant's hook runs before its ancestor's, and siblings' mounted hooks run in document order, which is Vue's own order. Several targets queue their hooks to keep it (queueHook), so a hook may run in a microtask after the framework's own. The queue is one for the page, so a directive from a .uf.ts module and a component's own sort together. Astro runs nothing in the page, so the element renders without its directive (directive, for information).

Transition

<Transition name="fade"> holds one element, or one conditional whose every branch is one element or nothing (UF3057), and name and appear are literals (UF3058). When the element enters, it carries fade-enter-from and fade-enter-active before it is first painted, then fade-enter-to without fade-enter-from from two frames later, and no class of the transition once it ends. When it leaves, the same runs with the -leave- classes, and the element stays in its place until the end, then goes.

The end is the element's own transitionend or animationend, or its longest duration and delay, whichever comes first, and with no duration the element is settled by the end of its second frame. The element's own classes stay on it throughout.

A swap of the conditional's branches runs the old element's leave and the new one's enter at once, so both are in the DOM until the leave ends, even when both are the same tag. With appear, the first element runs the enter on a client mount, and without it, only a change of the child runs a transition. The server renders the settled child, with no class and no wrapper. When the component that holds the <Transition> unmounts, or a condition around the <Transition> turns false, the child goes at once, with no leave.

Astro runs nothing in the page, so it renders the settled child (transition, for information).

Async setup

An async component awaits at the top of its setup, each value as the whole value of a const (UF2038), before every other item and reading only props, module values, globals and the values awaited before it (UF2039). The server waits for the setup and renders the resolved template, with no fallback and no wrapper. A client mount renders nothing until the setup resolves, then renders it (async-setup/resolved, async-setup/nested).

The awaited call reads its props once, so a later prop changes what the template reads, not what the setup loaded (async-setup/props). After hydration, the setup runs again on the client while the server's DOM stays as it is, with no mismatch reported, and the component becomes interactive once the setup resolves: its mounted hooks run then (async-setup/rerun). A component must not depend on its setup running once across the server and the client, nor on it running twice: Qwik resumes without running it again.

Solid creates the hydrated subtree again once the setup resolves, so focus and selection inside it reset. Solid 2 hydrates it in place with the values its server render serialized, so its awaits don't run again on the client. A React component whose props change while it hydrates renders on the client instead (async-setup, declared on the targets page).

Outside the contract

The outputs behave the same for every value and every sequence of actions that the rules above cover, with these exceptions. Avoid them: the compiler cannot see them.

  • Writing NaN over NaN, or -0 over 0. Vue compares values with Object.is, and Svelte's state and Solid's and Qwik's signals with ===: there, NaN over NaN runs a watchEffect that reads it again, and -0 over 0 calls back no watcher, where Vue's does.
  • Code that depends on whether two writes separated by an await call a watcher back once or twice, or on the order of two watchers. Writes in two tasks with no render between them, such as two timers' callbacks, may call a watcher back once on React, Angular and Qwik, which render in a task of their own. await nextTick() between the writes separates them.
  • On Solid, the order of the onMounted hooks and a watcher that a write during the setup triggers, such as an immediate watcher's: Solid calls the watcher back after the hooks, Vue before them.
  • On Solid, the states between two writes of one synchronous run. Solid renders each write as it is made, where Vue renders the run's last state. So a template or a getter that throws on such a state (a list shrunk before its selected index moves) stops the run half-written, and a run that hides an element and shows it again creates it anew, without its focus or what was typed. Write in an order whose every state renders.
  • On Solid, the elements a scoped slot's fill renders, when the child passes that call new props, such as a renamed item of its list. Solid runs the fill again, so its elements are new ones, without their focus or what was typed, and a directive on them runs unmounted and mounted where the other targets run updated on the same element.
  • Code that depends on a listener having run when emit returns.
  • An emit after the component is removed.
  • Where code after await nextTick() runs. It runs in the task that wrote on Vue, Svelte, Solid and Angular, and on React after a click's or a key's handler. React resumes in a later task after other writes (a watcher's, a hook's, a timer's, or code's after an await) and where the component's watchers write in response, and Qwik always does. There, the next event of the same input may run first: Enter's keypress after its keydown, which activates a focused button. Act on the event that ends the gesture, or prevent the key's default.
  • nextTick() on Qwik after a render that takes longer than about 15 milliseconds: Qwik yields, and the promise may resolve before the DOM shows the writes.
  • Code that depends on an async listener's continuation running before a later listener of the same event. On Vue, the browser runs the microtasks between two listeners, so a continuation after an await that resolves at once may run first. React, Svelte and Solid run the template's listeners from one delegated listener, and Angular, React and Qwik run an element's listeners of one event in one handler, so the continuation runs after the later listener. Do what a later listener needs before the first await.
  • Mixing a template listener and a listener that client code adds with addEventListener where their order or a stopPropagation() between them matters. The added listeners run in the DOM's order. React, Svelte and Solid run the template's listeners from a delegated listener at their root (Solid at the document): a template listener's stopPropagation() cannot stop a listener added to an ancestor or the document, and an element's own added listener may run before a descendant's template listener. Qwik runs every template listener from the document's capture phase, before any listener added to an element, the target's own included: a template listener's stopPropagation() keeps the event from them all, and theirs stops no template listener. Listen to such an event in the template only, or with addEventListener only.
  • A listener's first run on Qwik. Qwik loads a listener's code when the listener first runs, and until then the listener runs after the event's dispatch, preloaded or not. On that run it reads the DOM after the event's default action (a keydown listener sees the field after the key changed it), finds clipboardData and dataTransfer empty, and its own preventDefault(), stopPropagation() and stopImmediatePropagation() do nothing; the listeners of one input run in the order their code arrives. Once each listener has run once, Qwik runs them as every target does. The browser tests check that state: the Qwik adapter loads every listener's code before each input. Of the first-run differences, only a control that a $ function calls is reported, on the console (L13). Write a control that Qwik must honour on the first event where Qwik runs it at dispatch: at the top of the listener, alone or under a test of the event. Read what the event carries from the event (event.key, not the field's value after a keydown). A first read of clipboardData or dataTransfer has no portable spelling on Qwik.
  • On Angular, a keyed list of strings or numbers replaced whole, whose values are its keys. Angular's development mode warns NG0956: its advice for a list of objects created again with the same content. Every target creates the new rows, as the keys ask.
  • The focus on an element that its list moves. The browser blurs a moved element, and react-dom alone puts the focus back after it commits, so on the other targets the focused row loses its focus when it moves itself, and keeps it when the rows around it move.
  • A model bound to undefined. React, Solid and Qwik read it as unbound, and keep local state from the model's default. Bind a model to a value that is never undefined.
  • A slot fill that renders nothing. Vue shows the slot's fallback for it, and the other targets render nothing.
  • Text typed through an input method editor, as for Japanese or Chinese. Vue writes a v-model's ref once the composition ends, and the other targets on every input event during it.
  • The default value of a form control that v-model binds: what form.reset() restores and what a [value="…"] selector matches. Vue's is the server's value, or none, and React's follows the current value.
  • Whether a parent's lifecycle hooks run before or after its children's.
  • On React, what a listener of a checkbox's or a radio's input reads from its v-model. React writes the model on click, before the DOM's input, so the listener reads the value the click wrote, where Vue's reads the value from before the click.
  • On React, what code that runs later, after an await or in a timer, reads from a provided ref: the value of the component's last render, where the other targets read the current one.
  • On React, when a v-model_lazy field writes its ref: as the field loses focus, where Vue writes on change, which Enter fires too.
  • Markup that its element does not permit as content, set with innerHTML. The server's HTML is parsed as part of the page and the browser's markup inside the element, so a <div> inside a <p> closes the <p> on the server and stays inside it in the browser. Most servers also drop a line feed that starts the markup of a <pre>.
  • A <script> in markup set with innerHTML. It runs when the server's HTML arrives, and not when the browser sets the markup.
  • On a teleport, code in the onMounted of the component that holds it, which may run before the teleported element exists: Vue, Solid, Svelte, Angular and Qwik mount it in a later render. A component inside the teleport sees it in its own onMounted.
  • Whether an element outside a teleport hears an event from inside it. React's synthetic events bubble through a portal to the component's ancestors, the DOM's events don't. Listen inside the teleported element.
  • A teleport whose to matches no element when its content mounts. Each target renders nothing.
  • A selector that reaches a teleported element through an ancestor it left, like .panel .dialog. It no longer matches, while selectors on the teleported element and what it holds do.
  • On a directive, whether a document listener that mounted adds hears the event that rendered the element. Vue and Svelte render during the event's dispatch, so the listener hears it, and Solid after its handler, so it doesn't. Put a click-outside directive on an element that is already rendered.
  • On a directive, a teleported element's place when mounted runs. Qwik moves the element into to after the mount.
  • A directive's value of another type than its defineDirective<T>, under the default type oracle. TypeScript doesn't type a dashed JSX attribute, so the source type-checks, and only the outputs that type a directive's value catch it. The tsgo oracle reports it as UF6007.
  • On React, a directive under development StrictMode: React attaches a ref and runs its effects twice, so mounted, unmounted and mounted run, as onMounted's do.
  • The order in which the teleports of several components mount together, like a parent's and its children's. Vue and Qwik mount a parent's before its children's, and React, Svelte, Solid and Angular its children's first. A teleport that mounts later, once the others have, goes after them on every target.
  • On a transition, whether appear's enter runs as a server render hydrates or resumes. Vue runs it, and Svelte doesn't. The page settles to the server's HTML either way.
  • On a transition, the order of the two elements while a swap runs.
  • On a transition, how a change of the condition back while a leave runs looks. Vue removes the leaving element and enters a new one, Svelte reverses the leave, and Angular keeps the old element leaving beside the new one. Either way the shown element ends with no class of the transition (transitions/reverse).
  • On a transition, whether a leaving element still updates. It keeps its last render on Vue, React, Svelte, Solid and Angular, and may update on Qwik.
  • On a transition, a bound class on its element that changes while the transition runs, which can cut the transition short on every target but Vue.
  • On a transition, prefers-reduced-motion, which no target reads, as Vue doesn't.
  • On a transition, a duration over 4 seconds on Angular, which removes a leaving element after 4 seconds.
  • On a transition, when a directive's unmounted runs on the element that leaves: as the leave starts on Vue, Solid and Angular, and once it ends on React, Svelte and Qwik. By the end of the leave it has run on every target.
  • On a transition, which rule applies when its child's own condition and a condition around the <Transition> turn false in the same update.
  • On a transition, how long Svelte keeps a leaving element: it ends the leave by the element's duration, read as the leave starts, not by its transitionend.
  • On an async setup, a resolved value that differs from the server's. Every hydrating target shows it, and Vue and React also report a hydration mismatch, as for any render that differs from the server's. Load the same data on both sides.
  • On an async setup, a parent's ref to the component, and its exposed functions, before the setup resolves. They are usable once it has resolved on every target.
  • An async setup whose promise rejects. Each target throws its own way, and nothing catches it yet.
  • An async setup slower than the page's settling, which the tests can read as settled while it runs. The tests' setups resolve after a microtask.
  • Whether a parent's markup waits for an async child on a client mount. Svelte's does, and the other targets render it at once.

The differences the compiler can see are capabilities, reported at the first use: on Qwik, conditional-event-control (an error) and late-prop (a warning); on Vue, listbox; on Angular, contextual-root and default-slot-presence (errors); on Qwik, default-slot-presence too; on React and Solid, composable-effect-order (for information, UF4005); on Astro, interactivity and the capabilities that refine it, context, reactive-context, teleport and transition.

The decisions behind this page are ADR-0045, ADR-0046, ADR-0047, ADR-0048, ADR-0049, ADR-0050, ADR-0054, ADR-0058, ADR-0069, ADR-0070, ADR-0095, ADR-0096, ADR-0097, ADR-0098, ADR-0100 and ADR-0101.

Copyright © 2026