Agent Skills: Qwik Knowledge Patch

Qwik Knowledge Patch

Use this skill when creating, upgrading, reviewing, or debugging Qwik and Qwik City applications. Check the breaking changes and deprecations first, then open the topic reference that matches the work.

Reference index

| Reference | Topics | | --- | --- | | Async Reactivity and State | Async computations, tasks, stores, untrack(), and computed notifications | | Build and Deployment | Optimizer behavior, Vite options, assets, preloading, manifests, caching, CLI integrations, and deployment | | Components and Events | MDX components, view-transition events, and error boundaries | | Migration and Packaging | Library publishing, mixed-generation consumers, and peer dependencies | | Router and Navigation | Navigation blocking, previous URLs, rewrites, and redirect caching | | Server and Route Data | Server errors, middleware responses, route-data caching, mocks, origins, and request events |

Breaking changes and deprecations

Do not use async useComputed$ callbacks

Async useComputed$ callbacks are deprecated. Reads made after the first await are not tracked, and an initial promise restarts rendering. Move asynchronous work to useTask$ or useResource$.

Remove deprecated task eagerness

The eagerness option on useTask$ is deprecated as of 1.13. Remove it from new work and do not base scheduling behavior on it.

Migrate away from built-in service-worker prefetching

Automatic bundle preloading now uses modulepreload links and the bundle graph. The built-in service-worker components are deprecated. For an uncustomized worker, remove service-worker.ts but temporarily keep ServiceWorkerRegister so old deployed workers and caches can be removed. Retain the integration only for custom worker logic.

Replace deprecated preload probability

The preloadProbability SSR option is deprecated as of 1.16.1. Use the current preload controls, including the stable maxIdlePreloads concurrency limit.

Update asset and cache rules

Default assets use assets/hash-name.ext. Update deployment rules that rely on older paths. Content-hashed files below build/ and assets/ should normally receive a one-year immutable cache policy unless Rollup output names have been customized.

Match the supported Vite major

Qwik core and Qwik City use Vite 7 as of 1.16. Applications must install that major directly. Vite is a peer dependency of the Qwik packages, which avoids duplicate Vite imports but makes the application's dependency explicit.

Republish libraries for current consumers

Qwik library builds stopped applying the Qwik transform as of 1.9. Library authors should publish a new build and extend the accepted Qwik range with | ^2.0.0 where cross-generation consumption is intended.

Build and deployment quick reference

Preserve plugin transform ordering

The optimizer accepts import ... with, replaces eligible enums with numbers, and delegates QRL grouping to Rollup. Keep CSS-in-JS and other Rollup/Vite transforms ordered so they can process source before Qwik.

Always transform library QRL files

A qwikVite() fileFilter cannot exclude *.qwik.js, *.qwik.mjs, or *.qwik.cjs; those library QRL files are always processed.

Configure experimental features explicitly

Pass feature names through the experimental array:

qwikVite({ experimental: ['noSPA', 'valibot', 'preventNavigate'] });

Use noSPA only for MPA-only applications that do not use Link. preventNavigate enables usePreventNavigate, including asynchronous SPA blocking and browser-dialog fallback for other unsaved-state navigation.

Tune SSR preload behavior

renderToStream(<Root />, {
  ...opts,
  preload: { debug: true, maxIdlePreloads: 5 },
});

Use debug for preload diagnostics and maxIdlePreloads to cap concurrent idle preloads. A prefetch strategy may set linkFetchPriority on generated modulepreload links.

Handle Qwikloader delivery intentionally

SSR normally loads Qwikloader from a separate bundle. Testing and unusual network environments can opt back into embedding it:

renderToStream(<Root />, { ...opts, qwikLoader: 'inline' });

Verify generated artifacts

The preloader bundle graph is emitted as an asset, and generated assets appear in q-manifest.json. Current output filters core.js and preloader.js references from both the manifest and bundle graph. Run qwik check-client to detect a stale client bundle.

Reactivity and state quick reference

Unwrap stores only at integration boundaries

Use unwrapStore() when an API such as structured cloning or IndexedDB needs the store's underlying content:

import { unwrapStore } from '@builder.io/qwik';

const copy = structuredClone(unwrapStore(store));

Read without subscribing

untrack() accepts signals and stores directly, and its callback form accepts arguments:

const value = untrack(signal);
const result = untrack((a, b) => a + b, 1, 2);

The expression "prop" in store has the opposite behavior: it creates a subscription to changes in that property's presence.

Expect value-based computed notifications

Computed signals notify listeners only when the computed value changes. A dependency update that produces the same result does not notify them.

Router and server quick reference

Handle an absent previous URL

The router's previous URL is undefined on the first render. Guard code that uses it rather than assuming a prior navigation exists.

Rewrite without changing the visible URL

Throw the result of RequestEvent.rewrite() from the handler:

export const onRequest: RequestHandler = async ({ rewrite }) => {
  throw rewrite('/articles/42');
};

Multiple rewrite routes may target the same destination. The browser-visible URL remains unchanged.

Treat redirects as uncacheable by default

Redirects do not inherit a parent layout's Cache-Control header and default to no-store. Apply an explicit policy only when the redirect is safe to cache.

Expect thrown client-call failures

Client calls to server$ throw for 4xx statuses and statuses above 500; 499 is accepted. Middleware marked with @plugin can catch server$ failures, and server-function and route-loader errors use standardized handling.

Component and integration quick reference

Customize imported MDX

Imported MDX accepts a components prop, JavaScript expressions can read props, and default-exported MDX layout components are honored:

import Content from './markdown.mdx';
import MyComponent from './my-component';

export default component$(() => (
  <Content components={{ MyComponent }} />
));

Listen for view transitions

Qwik emits a CustomEvent named qviewTransition when a view transition starts. Use that exact event name for integration listeners.

Use the framework error boundary

Qwik provides ErrorBoundary; useErrorBoundary also has corrected behavior as of 1.13. Prefer these APIs for component-level failure handling.

Enable optional integrations deliberately

The Tailwind integration supports Tailwind CSS 4, while the CLI can retain Tailwind CSS 3. Scaffold compiled internationalization with qwik add compiled-i18. Because the Vite lint option defaults to false, enable linting explicitly when the build must run it.