English for Qwik City Developers
Vocabulary for developers building sites with Qwik City — resumability, routing conventions, route loaders, and actions — for teams discussing meta-framework architecture in English.
Qwik City is the meta-framework built on top of Qwik, adding file-based routing, layouts, and data-loading conventions on top of Qwik’s core idea of “resumability.” Because Qwik’s whole pitch is a departure from the hydration model most frontend developers already know, explaining it clearly in English matters — get the vocabulary wrong and you’ll accidentally describe it as “just another SSR framework” when the actual value is elsewhere. This guide covers the terms.
The Core Idea: Resumability
Resumability — Qwik’s central concept: the server sends a fully interactive page along with serialized application state, and the browser “resumes” execution exactly where the server left off, without re-running component logic to attach event listeners. “Because of resumability, this page has zero JavaScript execution cost on load — the browser only downloads and runs the tiny bit of code needed for the button you actually clicked.”
Hydration — the traditional approach (used by most frameworks) where the browser re-runs your entire component tree after the server sends HTML, to attach event listeners and rebuild state.
“We’re used to explaining hydration cost to stakeholders — with Qwik, that explanation mostly disappears because there’s no hydration step to begin with.”
Serialization boundary — the point where Qwik decides what state and closures need to be captured and sent to the client so execution can resume there later.
“We hit a serialization error because we tried to capture a non-serializable object — a raw DOM reference — across the serialization boundary.”
Lazy Loading
Lazy-loadable chunk — Qwik automatically splits your code into small chunks at every event handler and component boundary, so only the code needed for a specific interaction downloads, and only when the user actually triggers it.
“The
onClick$handler for this button lives in its own chunk — it’s not downloaded at all until the user hovers or clicks it.”
$ suffix (dollar sign convention) — a naming convention in Qwik marking a function or import as a lazy-loading boundary, signalling to the optimizer where it can split code.
“Anything named with a trailing
$, likecomponent$oronClick$, is a hint to Qwik’s optimizer about where to create a lazy-loadable boundary.”
Qwik City Routing
File-Based Routing
File-based routing maps files inside src/routes directly to URL paths, similar to Next.js or SvelteKit, but layered on top of Qwik’s resumable rendering model.
“Adding a new page is just adding a new file under
src/routes— no separate route configuration file to update.”
Route Loader
A route loader (routeLoader$) runs on the server to fetch data for a route before rendering, exposing that data to the component in a fully typed way.
“The route loader fetches the product data server-side — the component just calls the returned hook and gets fully typed data back.”
Action
A route action (routeAction$) handles form submissions and mutations on the server, integrating with progressive enhancement so forms work even before JavaScript loads.
“We used a route action for the checkout form — it works even if JavaScript hasn’t finished loading yet, because the form posts normally and the server handles it.”
Layout
A layout wraps a group of routes with shared UI (like a nav bar), following a nested folder convention similar to other meta-frameworks.
“The dashboard layout wraps every route under
/dashboard, so we don’t repeat the sidebar markup on each page.”
Performance Vocabulary Specific to Qwik
Time to Interactive (TTI) — traditionally, how long until a page becomes fully interactive after hydration completes; with resumability, Qwik claims this cost is largely eliminated because there’s no hydration step blocking interactivity.
“Our TTI numbers on this page are close to zero because there’s effectively no hydration step waiting to complete before users can interact.”
Progressive enhancement — building a feature (like a form) so it works with basic HTML behaviour first, then gets enhanced by JavaScript once it’s loaded — critical for Qwik City’s actions to feel correct even on slow connections.
“Even on a throttled 3G connection, submitting the form still works — that’s progressive enhancement, not a fallback we bolted on separately.”
Explaining Qwik City to a Team
| Situation | Phrase |
|---|---|
| Explaining resumability to a skeptical teammate | ”It’s not that we’ve optimised hydration — there’s no hydration step at all. The browser resumes exactly where the server stopped.” |
| Justifying route loaders over client-side fetching | ”The route loader runs server-side before the page renders, so there’s no loading spinner or waterfall — the data is already there.” |
Describing the $ convention | ”Every $ suffix marks a lazy-loading boundary — it’s the compiler’s signal for where code can be split and deferred.” |
| Explaining a serialization bug | ”We passed a non-serializable value across a component boundary — the fix was to move that logic inside a $-wrapped function instead.” |
Common Mistakes
- Describing Qwik City as “SSR with better hydration” — the distinguishing claim is the absence of a hydration step, not a faster version of it.
- Forgetting to explain the
$convention when reviewing a new teammate’s code — without context, it looks like arbitrary naming rather than a compiler signal. - Calling a route loader a “getServerSideProps equivalent” without noting it returns a typed, reactive resource, not a one-time prop.
Practice Exercise
- Explain, in two or three sentences, why resumability changes how you’d describe page load performance to a stakeholder.
- Write a short code review comment explaining why a value needs to move inside a
$-wrapped function to avoid a serialization error. - Draft an explanation of a route action to a teammate coming from a framework that uses client-side form submission exclusively.