# Migrating to Qwik v2 Qwik v2 is a ground-up rewrite of the framework. This guide covers what's new, how to run the automated migration, and what to verify afterward. ## What's New in v2 - **Vite environment API** — Better monorepo and adapter support - **Vite 8 / Rolldown** — Out of the box compatibility - **Smaller serialized state** — Up to 30% smaller HTML - **HMR** — Instant browser updates without losing state - **Async `useComputed$`** — Replaces `useResource$` with auto-tracking, polling, concurrency control, and abort - **``** — Shows fallback UI while part of the page waits ## Quick Start 1. [Run the CLI](#run-the-migration-cli) 2. [Handle third-party libraries](#third-party-libraries) 3. [Check behavioral changes](#behavioral-changes) 4. [Migrate deprecated APIs](#deprecated-apis) 5. [Run the checklist](#verification-checklist) --- ## Run the Migration CLI ```shell pnpm qwik migrate-v2 ``` The CLI handles package renames, identifier changes, config updates, and dependency migration automatically. **What the CLI renames** **Packages** | v1 | v2 | |---|---| | `@builder.io/qwik` | `@qwik.dev/core` | | `@builder.io/qwik-city` | `@qwik.dev/router` | | `@builder.io/qwik-react` | `@qwik.dev/react` | | `@qwik-city-plan` | `@qwik-router-config` | | `@builder.io/qwik/jsx-runtime` | `@qwik.dev/core/jsx-runtime` | **Identifiers** | v1 | v2 | |---|---| | `QwikCityProvider` | `QwikRouterProvider` | | `qwikCity` | `qwikRouter` | | `QwikCityPlugin` | `QwikRouterPlugin` | | `createQwikCity` | `createQwikRouter` | | `qwikCityPlan` | `qwikRouterConfig` | | `jsxs` | `jsx` | --- ## Third-Party Libraries If you use third-party libraries that depend on `@builder.io/qwik`, you may need to configure overrides and SSR bundling. ### Package manager overrides Redirect the old package name so your package manager doesn't install v1 alongside v2: ```json { "pnpm": { "overrides": { "@builder.io/qwik": "npm:@qwik.dev/core@^2", "@builder.io/qwik-city": "npm:@qwik.dev/router@^2" } } } ``` ### ssr.noExternal Qwik libraries must be bundled into the server build for the optimizer to process them: ```typescript // vite.config.ts export default defineConfig({ ssr: { noExternal: ['some-qwik-library'], }, optimizeDeps: { exclude: ['some-qwik-library'], }, }); ``` Without this, you'll see `Code(Q30)` duplicate runtime errors or "external dependency" warnings. --- ## Behavioral Changes These won't cause compile errors but will break runtime behavior if not addressed. ### useComputed$ now supports async In v1 `useComputed$` rejected async functions. In v2 it accepts them: pass an `async` function (or return a Promise) and the signal exposes `.pending`, `.error`, and `.value`. Qwik auto-tracks the signals and stores the function reads before the first `await`; reads after an `await` must use the `track()` provided on the context argument. ```typescript // v2 — useComputed$ handles async directly const data = useComputed$(async ({ abortSignal }) => { const result = await fetch('/api/data', { signal: abortSignal }); return result.json(); }); ``` **READING COMPUTEDSIGNAL.VALUE** `.value` throws while unresolved. Always branch on `.pending` / `.error` first, or provide an `initial` value. ```tsx let content: JSXOutput; if (data.pending) { content =

; } else if (data.error) { content =

Error: {data.error.message}

; } else { content =

{JSON.stringify(data.value)}

; } return

{content}

; ``` ### useVisibleTask$ eagerness removed The `eagerness` option (`'load'` / `'idle'`) was removed in v2. Delete it if present. ### QwikCityProvider → useQwikRouter Replace the `` wrapper with the `useQwikRouter()` hook: ```tsx // v1 import { QwikCityProvider, RouterOutlet } from '@builder.io/qwik-city'; export default component$(() => { return ( ); }); ``` ```tsx // v2 import { RouterOutlet, useQwikRouter } from '@qwik.dev/router'; export default component$(() => { useQwikRouter(); return ( <> ); }); ``` If your root component is reactive (reads signals), use `` instead. `useQwikRouter()` only runs once during SSR. ### Serialization v1 serialized state into `