Home › Qwik › Qwik + Qwik City rules
Qwik + Qwik City rules
Cursor rules for Qwik and Qwik City apps: resumability, $ boundaries, signals, routeLoader$ and routeAction$.
CursorQwik
How to use
Save this as .cursor/rules/qwik.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.
Note: Review and test before use. Provided as is, without warranty. See Terms.
.cursor/rules/qwik.mdcDownload ---
description: Qwik + Qwik City conventions
globs: ["src/**/*.{ts,tsx}"]
alwaysApply: false
---
# Qwik / Qwik City
- Check `package.json` for the Qwik major version and follow that version's docs; APIs below are the stable core.
- Components are `component$(() => ...)`. Anything crossing a `$` boundary (event handlers, tasks, `server$`) must be serializable: no class instances, functions captured from outside, or DOM nodes in captured scope.
- State: `useSignal()` for primitives, `useStore()` for objects, `useComputed$()` for derived values. Read `.value` in JSX.
- Effects: `useTask$` (runs on server and client, track deps with `track(() => sig.value)`) and `useVisibleTask$` only when you truly need the browser on load; it defeats resumability.
- Data loading via `routeLoader$` in `routes/**/index.tsx` or `layout.tsx`; mutations via `routeAction$` + `<Form action={action}>` with `zod$` validation. Use `server$` for ad hoc server calls.
- Event handlers: `onClick$={() => ...}`; use `preventdefault:click` attributes instead of `e.preventDefault()` when possible.
- Lazy-load heavy client libraries inside the handler/task that needs them (`await import(...)`).
- Routing is file-based under `src/routes/`; layouts via `layout.tsx`; head metadata via `export const head: DocumentHead`.
- Server-only code (DB, secrets) stays in loaders/actions/`server$` or files they import; read env via `requestEvent.env.get()`.
## Don't
- Don't port React patterns (`useEffect`, `useState`) or import React libraries without `qwikify$`.
## Done when
`npm run build` (includes type check) and `npm run lint` pass.