qwikdev/qwik/qwik-router-development

Qwik Router Development

Use this skill for packages/qwik-router/** work. Keep the repo-wide rules from .ruler/AGENTS.md in force.

Fast Path

1. Classify the touched router surface before editing: runtime, buildtime, middleware, adapter, SSG,

markdown/MDX, or Vite integration.

1. Read the smallest source file plus the closest *.unit.ts or *.spec.ts file before changing

behavior.

1. For middleware, loader, action, or navigation changes, trace handler ordering and shared state

from request creation through response/client consumption before editing.

1. For unit/spec coverage, run pnpm vitest run <path>.
2. For browser/router behavior, rebuild first with pnpm build.core.dev, then use the focused

Qwik Router e2e command.

1. If public router API markdown changes are expected, run pnpm api.update after tests pass.

Source Map

• Runtime: packages/qwik-router/src/runtime/src/
• Buildtime route generation: packages/qwik-router/src/buildtime/
• Vite integration: packages/qwik-router/src/buildtime/vite/
• Middleware: packages/qwik-router/src/middleware/
• Adapters: packages/qwik-router/src/adapters/
• SSG: packages/qwik-router/src/ssg/
• Router e2e tests: e2e/qwik-e2e/tests/qwikrouter/

Verification

Use the closest command that covers the changed surface:

pnpm vitest run packages/qwik-router/src/buildtime/routing/parse-pathname.unit.ts
pnpm vitest run packages/qwik-router/src/runtime/src/client-navigate.unit.ts
pnpm build.core.dev
pnpm playwright test e2e/qwik-e2e/tests/qwikrouter/nav.e2e.ts --browser=chromium --config e2e/qwik-e2e/playwright.config.ts

Do not use --project chromium with e2e/qwik-e2e/playwright.config.ts; this config expects the --browser=chromium flag.

Quality Bar

• Keep middleware, loader, and action ordering explicit. Do not add broad fallbacks that hide which

module owns a request.

• Add regression tests for the exact route shape or request mode that failed, such as index route,

layout loader, page loader, redirect, action, or SPA navigation.

• When changing serialized route state or loader data, update both server output and client

consumption in the same change.

• Preserve deprecated Qwik City compatibility only when current source still supports it, and keep

compatibility warnings/tests intentional.

• If router work exposes stale guidance here or in .ruler/AGENTS.md, update the guidance before

finishing or record why guidance edits were out of scope.

Stop Conditions

• Stop and inspect the generated API workflow before hand-editing any *.api.md file.
• Stop and switch to qwik-e2e-verification when most of the work is Playwright setup/debugging.
• Stop and run pnpm api.update if exported router API changed.