/web-meta-framework-qwik

name: web-meta-framework-qwik
description: Qwik resumable framework - zero hydration, $ lazy boundaries, signals, Qwik City file-based routing, routeLoader$, routeAction$, server$ RPC, serialization rules

Qwik Patterns

> **Quick Guide:** Qwik is resumable rather than hydrated — the server serializes application state into > the HTML and the client picks it up without re-executing framework code. Every `$` suffix marks a > lazy-loading boundary the optimizer splits into its own chunk, so only the code for the interaction a > user actually triggers is downloaded. `component$` wraps every component, `useSignal`/`useStore` hold > state, `routeLoader$` supplies server data, `routeAction$` handles mutations, and `server$` is ad-hoc > RPC. The constraint everything else follows from: anything captured across a `$` boundary must be > serializable.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — typed props, signals, stores, tasks, resources, events, scoped styles
• [examples/routing.md](examples/routing.md) — route files, nested layouts, loaders, actions, `server$`, endpoints, middleware, navigation
• [examples/serialization.md](examples/serialization.md) — what crosses the `$` boundary, `noSerialize`, lean closures, QRL props
• [reference.md](reference.md) — project layout, import cheat sheet, serializable-type table

---

Which path applies

The two packages divide the surface, and mixing up which one an export comes from is the commonest import error.

• **Component work** — components, state, lifecycle, events, slots, styles, all from

`@builder.io/qwik`. Follow [examples/core.md](examples/core.md).

• **Route and server work** — routing, layouts, loaders, actions, `server$`, endpoints and middleware,

all from `@builder.io/qwik-city`. Follow [examples/routing.md](examples/routing.md).

---

<critical_requirements>

Before writing Qwik code

**Wrap every component in `component$()`.** A plain function cannot be lazy-loaded, cannot call hooks and cannot host `<Slot />`.

**Keep everything captured in a `$` closure serializable.** A non-serializable capture type-checks and then fails at runtime, which is why the compiler is no help here.

**Reach for `routeLoader$` for initial server data rather than fetching in `useTask$` or `useResource$`.** Loaders run before render and integrate with SSR streaming, so there is no loading state to show.

**Cancel default behaviour with the `preventdefault:click` JSX attribute rather than `event.preventDefault()`.** Handlers load asynchronously, so the synchronous Event APIs have already had their effect by the time the handler runs.

**Export `routeLoader$` and `routeAction$` from a route file** — `index.tsx` or `layout.tsx` under `src/routes/`. Anywhere else, or unexported, they silently do nothing.

**Read and write store properties through the store reference — `store.name`.** Destructuring extracts the value from the Proxy, and reactivity goes with it.

</critical_requirements>

---

**Auto-detection:** Qwik, component$, useSignal, useStore, useTask$, useVisibleTask$, useComputed$, useResource$, routeLoader$, routeAction$, server$, sync$, QRL, noSerialize, @builder.io/qwik, @builder.io/qwik-city, Qwik City, $(), onClick$, onInput$, Slot, q:slot, preventdefault, stoppropagation, useStylesScoped$, resumable, resumability

**Applies to:**

• Resumability, the `$` suffix, and what the optimizer does with it
• Components: `component$`, typed props, QRL callback props, `<Slot />` projection
• Reactive state: `useSignal`, `useStore`, `useComputed$`
• Lifecycle: `useTask$`, `useVisibleTask$`, `useResource$`
• Events: `on{Event}$`, `preventdefault:`/`stoppropagation:` attributes, `sync$`, global listeners
• Qwik City routing: file-based routes, nested and named layouts, dynamic params, route groups
• Server work: `routeLoader$`, `routeAction$`, `server$`, endpoint handlers, `onRequest` middleware
• Serialization rules and how to work around them

**Handled elsewhere:**

• Which CSS system fills a scoped style block — Qwik settles how styles attach to a component, not how they are authored.
• Validation schemas beyond the shape `zod$()` wraps — the action integration is Qwik's, the schema language is not.
• Databases, mail and other services called from inside `server$` or a loader — those functions are just server code.
• Statically-generated content sites with little interactivity — resumability buys nothing where there is nothing to resume.

---

<philosophy>

Qwik is built on **resumability**. A hydrating framework renders HTML on the server and then re-executes every component on the client to reattach listeners and rebuild the tree. Qwik does not: the server serializes the tree, the state and the listeners into the HTML, and the client resumes from there. When a user clicks a button, that handler's chunk is what downloads — not the framework, not the tree, not the other handlers.

**The `$` suffix is the mechanism.** Each `$` is a split point the optimizer turns into a separately loadable chunk: `component$()` for a render function, `onClick$()` for a handler, `useTask$()` for a tracked effect, `routeLoader$()` for server-only code.

**The price is serialization.** A chunk that loads later needs its captured scope restored from the HTML, so a `$` closure can only close over values Qwik knows how to write down. Class instances, functions and DOM nodes are not among them, and that single constraint explains most of the API's unfamiliar corners — `QRL` props, `noSerialize`, the advice to keep closures lean.

</philosophy>

---

<decision_framework>

**Which state primitive?** A single primitive is `useSignal`, read and written through `.value`. An object or array is `useStore`, mutated property by property with deep tracking on by default. A value derived synchronously from others is `useComputed$`. A value derived asynchronously is `useResource$`. Data that comes from the server is `routeLoader$`.

**Which lifecycle hook?