QwikDev/qwik
github.com/QwikDev/qwik ↗ · 4000 files · 14.0 MB · scan capped
Instant-loading web apps, without effort This is the branch for Qwik v2, currently in beta.
Overview
Qwik v2 is a web framework for developers building server-rendered applications that resume execution from serialized state and load event code on demand. This monorepo contains the reactive runtime, SSR engine, TypeScript and Rust optimizers, routing and deployment adapters, project scaffolding, React integration, developer inspection tools, and an Insights analytics application. Its distinctive architecture connects extracted QRL functions, build manifests, HTML metadata, and lazily restored client state. This brief reflects bounded, read-only inspection at commit 8eb4589be115eb8f2dabfd12c107dcc23647caec; no repository code, tests, builds, or workflows were executed.
System map
The repository distributes a framework through several packages rather than running as one application. Core exposes separate client, server, optimizer, and CLI surfaces, while Router connects generated route configuration to platform middleware. Supporting applications include documentation and Insights, and development tooling includes MCP inspection. Build and deployment commands below are source-defined capabilities, not commands executed during this investigation.
- The pinned branch describes Qwik v2 as resumable, with VNode runtime work, rewritten reactive primitives, and a new serialization mechanism.
- @qwik.dev/core publishes conditional development/production runtime exports, an internal surface, JSX runtime exports, and a qwik CLI executable.
- renderToString delegates to renderToStream; streaming creates an SSRContainer, installs the server platform, renders JSX, and flushes buffered output.
- Browser startup is owned by qwikloader.ts, which turns window._qwikEv into a registration object and installs scoped event listeners.
- Router has buildtime-generated virtual modules and shared runtime route matching; requestHandler is the request entry used by adapters.
- createQwikPlugin selects @qwik.dev/ts-optimizer or @qwik.dev/optimizer; QWIK_OPTIMIZER=ts|rust overrides the option and invalid values throw.
- The Rust workspace includes optimizer core and NAPI members, lists then excludes the WASM member, and configures a size-oriented release profile.
- Insights owns persistent application, symbol, error, and manifest tables through Drizzle's libSQL database type and an initialized module-level database handle.
- The workspace spans packages/* and e2e/*, requires strict engine compatibility, and pins pnpm 11.22.0 with Node >=22.18.0 at the root.
- Root build.core.dev, build.full, test.unit, and browser-specific test scripts define the contributor build/test surface; docs deployment consumes CI artifacts and publishes to Cloudflare Pages.
Feature catalog
The primary user is an application developer using components, reactive state, routing, server functions, and deployment adapters. The inspected public surfaces also provide scaffolding, React interoperability, lint rules, and local inspection tools. Insights adds telemetry ingestion and an authenticated dashboard foundation. This catalog covers evidenced feature families; the capped inventory and selective source reads do not establish an exhaustive list of every example, documentation screen, or integration.
- Core exports component$, QRL boundaries $, sync$, event$, JSX helpers, Slot, and client rendering APIs.
- Developer state APIs include useStore, useSignal, computed signals, async signals, contexts, scoped styles, tasks, visible tasks, resources, and serializers.
- Each, Show, Pending, and Catch are exposed control-flow/error primitives; optimizer experimental flags include each, show, pendingBoundary, catchBoundary, and blockSSR.
- Event handling supports element, document, and window scopes, passive variants, preventdefault attributes, stoppropagation attributes, and late registrations.
- routeLoader$ supplies ComputedSignal data, per-loader endpoints, search-parameter allowlists, ETags, cache-control options, and strict-loader defaults.
- Route actions provide browser submission state and form completion events; JSON action handling runs validators and can return explicit loader invalidation hashes.
- server-function requests can return either a serialized value or an async-iterator stream using application/qwik-json and text/qwik-json-stream.
- Router exposes adapters for Azure SWA, Cloudflare Pages, Cloud Run, Bun, Deno, Node, Netlify Edge, static generation, and Vercel Edge.
- create-qwik supports argument-based or interactive startup; the argument path accepts template, output directory, --force, and --installDeps.
- React interoperability exports qwikify$ and reactify$; qwikifyQrl tracks props, resolves the React component lazily, maintains a React root, and schedules root cleanup.
- Developer tooling includes recommended/strict ESLint rule sets and MCP tools for project information, route lists, browser errors, page inspection, and offline documentation.
- Insights accepts symbol timing telemetry, mounts an Insights component and RouterOutlet, and integrates GitHub sign-in, sign-out, and session APIs.
Data flow
Qwik transforms application code into addressable functions and associates runtime references with build manifests. SSR emits HTML plus container and state metadata, which the client consumes when execution resumes. Router transports action and loader results through Qwik serialization, while Insights converts validated telemetry into statistical database updates. Scaffolding follows a separate filesystem path that stages template merges and optionally invokes a package manager.
- Optimizer extraction records immutable symbol names, hashes, canonical filenames, byte offsets, body text, and QRL callee metadata for subsequent pipeline phases.
- resolveManifest merges the built and supplied manifests, then maps symbol hashes to symbol names and bundle filenames.
- SSR openContainer emits paused state, runtime version, build base, locale, manifest hash, and instance hash as container attributes.
- emitStateData directs the serialization context into the SSR writer inside a qwik/state script; eager-resume roots add an idle-event QRL.
- The documented state representation alternates type identifiers and encoded values, references shared roots, resolves promise forward references, and restores objects through allocation and inflation.
- DomContainer parses qwik/state, preprocesses roots, chooses eager restoration or wrapDeserializerProxy, processes segment state when enabled, and marks the container resumed.
- Event attributes encode chunk, symbol, and capture IDs; dispatch resolves the chunk relative to q:base and invokes the handler with capture IDs as its this value.
- SignalImpl.value reads register effect subscriptions and back references; changed writes update the stored value and call scheduleEffects.
- submitAction sends FormData or JSON to ?qaction=ID and decodes the response with _deserialize; actionHandler serializes result and optional loaderHashes.
- fetchRouteLoaderData constructs a manifest-versioned loader URL, optionally forwards the page path, caches requests by URL and full-path header, and handles redirects and aborts.
- Insights parses incoming JSON with InsightsPayload, normalizes symbol names, buckets delay/latency/timeline measurements, and passes application/manifest identifiers into updateEdge and updateRoutes.
- createFromStarter writes initial package metadata and README, stages base and optional starter integrations through updateApp, and applies their filesystem writes through commit callbacks.
Behavior traces
Four concrete flows were followed across their owning files: a server-rendered page and resumed event, a route action, project scaffolding, and Insights ingestion. These traces describe source control flow rather than observed runtime executions. They expose explicit synchronization points: SSR flushes, streamed-container readiness, action submission serialization, and database writes after response creation.
- Page request, step 1: createQwikRouter.router computes the origin, combines body limits, calls fromNodeHttp, and passes the resulting event to requestHandler.
- Page request, step 2: requestHandler obtains getRouterConfig, loads routes through loadRequestHandlers/loadRoute, resolves middleware, and calls runQwikRouter.
- Page request, step 3: runQwikRouter creates RequestEvent and drives runNext; page middleware runs actions/loaders before renderQwikMiddleware supplies serverData and a stream to the application's render function.packages/qwik-router/src/middleware/request-handler/user-response.ts#L29-54packages/qwik-router/src/middleware/request-handler/user-response.ts#L85-103packages/qwik-router/src/middleware/request-handler/resolve-request-handlers-core.ts#L131-138packages/qwik-router/src/middleware/request-handler/resolve-request-handlers-core.ts#L795-809
- SSR step: renderToStream resolves manifest/base, creates StreamHandler and SSRContainer, calls setServerPlatform and container.render, awaits the render promise, then flushes.
- Resumed click step: qwikloader dispatch reads q-e:click, locates the container, waits for its ready marker when streaming, resolves/imports the handler, and invokes it with captured IDs.
- QRL invocation step: _run obtains DomContainer, waits for container data, creates invocation context, deserializes capture deltas, and calls runEventHandlerQRL; that function inflates the host element and invokes through retryOnPromise.
- Action flow: routeActionQrl.submit queues behind pendingDispatch and updates currentAction; the router task calls submitAction, actionHandler parses/validates/calls the QRL, and the client receives result plus invalidation hashes.
- Scaffold flow: create-qwik.mjs calls runCli; arguments choose runCreateCli, which builds a template manager, validates the target-directory policy, and invokes createApp.
- Scaffold write/install flow: createApp calls createFromStarter, updateApp merges integration files, commit creates directories and writes files, and installDeps delegates to runCommand using execa.
- Insights persistence flow: plugin@db initializes the libSQL client; onPost parses and validates telemetry, sends an OK response, then resolves manifest/application records and awaits updateEdge/updateRoutes counter updates or inserts.
Testing signals
Tests and CI configuration were inspected, not executed; test existence is not a passing result. Vitest exercises package-level specifications, Playwright exercises browser and adapter behavior, and Rust optimizer tests use Insta snapshots. Inspected tests provide concrete coverage signals for serialization, streamed events, action responses, request limits, and database aggregation. Coverage remains bounded: this investigation did not establish complete test coverage or production behavior.
- The inspected root Vitest configuration includes package *.spec.* and *.unit.* files, excludes generated/dependency trees, loads vitest-setup.ts, and enables the TypeScript optimizer.
- Serialization tests snapshot encoded Plain and RootRef values and separately test decoding; additional assertions restore signal effect back references and compute QRLs.
- qwikloader.behavior.unit.ts reads dist/qwikloader.debug.js and executes it inside mocked browser globals, so its intended checks depend on current build output.
- A loader regression test asserts that a click does not run before streamed-container data is ready and runs after QwikEvContainerReady is pushed.
- Playwright events.e2e.ts checks independent counter updates, prevented navigation, propagation behavior, and mouseleave/mouseover execution ordering.
- Action-handler unit tests deserialize response bodies and assert default, explicit, and strict-mode invalidation semantics plus validator failure status.
- Request-body-limit tests cover exact-limit acceptance, oversized single/multiple chunks, and invalid limit configuration.
- Insights query tests use an in-memory libSQL client with explicit fixtures to check cross-manifest aggregation and isolation from another application's rows.
- Rust test_input_fn invokes transform_modules and snapshot_res records emitted modules, maps, segment metadata, and diagnostics using insta::assert_snapshot!.
- Core Playwright configuration uses *.e2e.ts, parallel execution, a localhost dev-server command, CI-only traces/screenshots, and forbidOnly; docs use a separate Chromium configuration.
- Inspected CI defines unit and MCP checks plus sharded browser runs with QWIK_OPTIMIZER set from TS/Rust matrix entries; no CI run result was retrieved.
- The inspected action unit harness mocks parseBody and QRL execution, and the Insights query fixtures test reads rather than the full authenticated ingestion path; those tests alone do not prove those integrations.
Risk map
The main sensitive boundaries are HTML/script generation, browser chunk loading, request routing and execution, scaffold filesystem writes, local inspection IPC, and privileged CI deployment. Concrete guards exist at several boundaries, including escaping, origin validation, byte limits, and loopback/token checks. Source inconsistencies and operational hypotheses below are not confirmed vulnerabilities. No runtime exploit, production configuration, credential value, or whole-repository absence was established.
- SSR escapes ordinary text and attribute values, while htmlNode writes raw HTML and dangerouslySetInnerHTML preserves supplied HTML; callers choosing raw output own a sensitive trust boundary.
- Backpatch scripts replace '<' with a Unicode escape and apply a supplied nonce; sync-function scripts also propagate serverData.nonce.
- Browser resolveHandler imports a URL derived from chunk metadata and q:base, then selects a named export; integrity of server-emitted QRL metadata is therefore a code-loading boundary.
- Router enables checkOrigin by default and prepends CSRF checks for mutation methods; the check compares origins for simple content types, with an explicit lax-proto mode.
- Server-function dispatch requires matching query hash/X-QRL and application/qwik-json, validates argument-array shape, and masks ordinary execution failures with an Invalid request response.
- Internal full-path headers must be relative absolute-path forms under the loader prefix; scheme-relative paths, foreign origins, and malformed URLs are rejected.
- limitRequestBody validates a positive safe integer and enforces a 10 MiB default by counting streamed bytes; Node middleware combines configured and caller-supplied limits using the smaller value.
- Loader result caching excludes redirect, error, and failed-result envelopes; developer-provided cache keys still define which successful serialized responses share cache entries.
- Scaffolding can clear an existing target directory under --force, write outside the repository into an absolute outDir, and invoke package-manager install through execa.
- MCP inspection guards its HTTP endpoint with loopback address, bearer token, absent Origin, exact Host, POST-only handling, and an 8192-byte request limit; discovery files use restrictive creation modes.
- Insights dashboard middleware requires a session email, but the inspected telemetry handler accepts a validated publicApiKey payload and permits auto-creation; schema validation is not itself proof of application ownership authorization.
- Insights sends its OK response before database operations finish, and counter-update comments explicitly accept missed-update risk from avoiding transactions.
Extension points
Extension mechanisms generally use explicit factories, branded functions, package exports, or declarative metadata. Runtime APIs and serializers connect to an optimizer-aware public boundary, while Router discovers middleware and data functions from route modules. Scaffolding discovers packaged integrations and composes them through a staged update interface. Tooling provides additional named registries for experiments, lint rules, and MCP tools.
- core/index.ts is the public export boundary for components, QRLs, hooks, state primitives, and control-flow helpers; new public APIs must fit this export surface.
- setPlatform and CorePlatform provide a named platform abstraction, while createQwikPlugin accepts an injected _optimizer before selecting built-in optimizer providers.
- ExperimentalFeatures is an explicit registry for compiler-replaced runtime flags, including control-flow primitives, validation, SPA behavior, Insights, and nonblocking loaders.
- routeLoaderQrl produces frozen server_loader functions carrying QRL, validators, ID, serialization strategy, cache-control, ETag, cache-key, search, and blockSSR metadata.
- routeActionQrl produces frozen server_action functions; resolveRequestHandlers discovers loaders/actions by examining branded exported functions in route modules.
- Route modules extend request execution through onRequest and method-specific onGet/onPost/onPut/onPatch/onDelete/onOptions/onHead handlers, each accepting a function or function array.
- qwikRouter builds a plugin array around router, server-function, and image plugins; ssgAdapter composes the shared viteAdapter with origin and SSG options.
- loadIntegrations discovers app, feature, and adapter directories and reads package __qwik__ metadata for display name, documentation, priority, and alwaysInRoot rules.
- makeTemplateManager separates standalone templates from base and treats library as a standalone bootstrap; updateApp returns staged updates plus a commit callback.
- Custom serialization APIs include useSerializer$ and createSerializer$; an inspected test supplies serialize/deserialize functions for a custom class.
- The ESLint plugin uses a rules table with recommended/strict severity maps, while createMcpServer defines tools through a named table of schemas and accepts an external call dispatcher.
Contributor handoff
Tests and CI were inspected, not executed, and this report is a bounded source inventory rather than exhaustive coverage or a verification certificate. Future work should begin at the package and protocol boundary implicated by the task. Serialization and routing changes require coordinated reader/writer inspection, while optimizer behavior must account for both implementations. Repository setup and verification guidance is recorded below for later authorized work; none of those commands ran here.
- Read root AGENTS.md and the owning package sources first; the monorepo map identifies core, Router, React, utilities, DOM, Vite integration, optimizers, scaffolding, docs, and Insights.
- Shared guidance originates in .ruler; generated AGENTS.md/CLAUDE.md should not be edited directly, and the inspected ruler-check workflow regenerates and checks their drift.
- The documented focused loop is build.core.dev followed by the closest Vitest test or Chromium Playwright file; this audit inspected that guidance without executing its setup or verification commands.
- Optimizer selection differs between local test configuration and default provider selection; account for tsOptimizer:true, QWIK_OPTIMIZER overrides, and Rust binding prerequisites when planning authorized checks.
- For state changes, read serialization.md, SSR emitStateData, and DomContainer's reader together; preserve type/value pairing, shared references, and the distinction between qwik/state and sync-function metadata.
- For action/loader protocol changes, inspect both server handlers and client transport; JSON-looking endpoints use Qwik serialization and have explicit invalidation, redirect, and caching semantics.
- Loader behavior tests consume built qwikloader.debug.js, so source-only edits without regenerated output can leave the intended verification testing stale artifacts. (inferred)
- Root tsc.check is not a substitute for every package's type checks: tsconfig.json explicitly excludes packages/qwik/src, scripts, and generated library trees.
- Preserve compatibility boundaries: qwikCity delegates to qwikRouter, staticAdapter aliases ssgAdapter, and Node notFound is a deprecated pass-through slated for V3 removal.
- Do not assume repository scripts are read-only: build/update scripts generate artifacts, scaffold commit writes files, and installDeps starts an external package manager.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 2619 | 95% |
| Markdown | 966 | docs/config |
| JSON | 247 | docs/config |
| JavaScript | 94 | 3% |
| CSS | 86 | docs/config |
| Rust | 25 | 1% |
| SQL | 20 | 1% |
| YAML | 12 | docs/config |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (2302 files)
Repository structure
| Top-level path | Files |
|---|---|
packages/ | 2302 |
e2e/ | 701 |
.changeset/ | 602 |
starters/ | 269 |
scripts/ | 54 |
.github/ | 12 |
.ruler/ | 10 |
patches/ | 5 |
Docs found: AGENTS.mdCLAUDE.mdCONTRIBUTING.mdREADME.md
Package
Cargo.toml — , 0 declared dependencies.
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructionsCLAUDE.md— Claude instructions.github/workflows/auto-assign-core-team.yml— GitHub Actions workflow.github/workflows/cancel.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflow.github/workflows/deploy-docs.yml— GitHub Actions workflow.github/workflows/ruler-check.yml— GitHub Actions workflowe2e/adapters-e2e/adapters/bun/vite.config.ts— Vite confige2e/adapters-e2e/adapters/deno/vite.config.ts— Vite config
Structural health signals
Average score 9/10 across 96 analyzed source files; 3 hotspots surfaced.
packages/docs/src/routes/(blog)/blog/(articles)/qwik-2-rc/rc-hero.tsx— 623 lines, score 5.5 (Large file, Deep nesting)packages/qwik-vite/src/plugins/vite.ts— 1246 lines, score 5.7 (Large file, Deep nesting)packages/qwik-router/src/middleware/node/http.unit.ts— 583 lines, score 6.2 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
8eb4589be1152026-10-02 — Merge pull request #9119 from QwikDev/fix-forward-back-routerc1d2309a8b352026-10-02 — fix(router): handle back/forward pressed before the SPA router has initialized9ca474c1cce32026-10-02 — Merge pull request #9118 from QwikDev/claude/funny-gates-iako7t3e8a0ae66cf62026-10-02 — ci: build docs previews with their own Cloudflare Pages originbdbd082902ad2026-10-02 — docs(blog): use the article hero as the default social image