Qwik guide React Server Components: What migration for Engineers

npm create qwik@latest "my-qwik-app"
cd "my-qwik-app"
npm install

s with RSC, leverage the Qwik City adapter for incremental adoption or port routing to Qwik's native file-based system.

2. Migrate Components Incrementally

Avoid big-bang migrations. Start with leaf components (no children/minimal dependencies):

• Replace RSC server-only components with Qwik components using server$ for server-side logic.
• Remove RSC-specific imports (e.g., react-server-dom-webpack) and substitute Qwik equivalents.
• Convert React event handlers to Qwik's lazy-loadable $ syntax: onClick$={() => ...}.

3. Port Data Fetching Logic

RSC async components map to Qwik's routeLoader$ for route-bound data or server$ for reusable server logic:

// RSC async component
async function ProductList() {
  const products = await db.query('SELECT * FROM products');
  return <ul>{products.map(p => <li key={p.id}>{p.name}</li>)}</ul>;
}

// Qwik equivalent using routeLoader$
import { routeLoader$ } from '@builder.io/qwik-city';

export const useProducts = routeLoader$(async () => {
  const products = await db.query('SELECT * FROM products');
  return products;
});

export default component$(() => {
  const products = useProducts();
  return <ul>{products.value.map(p => <li key={p.id}>{p.name}</li>)}</ul>;
});

4. Update State Management

Replace React state hooks with Qwik's reactive primitives to avoid full-tree re-renders:

• useState → useSignal for primitives, createStore for complex objects.
• useReducer → createStore with custom update functions.
• React Context → Qwik's useContext, createContext.

5. Migrate Routing and Navigation

Map existing routes to Qwik City's file-based structure:

• pages/index.tsx → src/routes/index.tsx
• Dynamic routes use [id].tsx syntax.
• Replace framework-specific Link components with Link from @builder.io/qwik-city.

6. Test and Validate

Update unit and integration tests using @builder.io/qwik/testing. Verify:

• Interactive components respond correctly to serialized event handlers.
• Server-only logic executes exclusively on the server.
• No client-side JS regressions or hydration mismatches occur.

Pitfall Guide

1. Hydration Dependency Trap: Assuming RSC's hydration model applies to Qwik. Qwik uses resumability; forcing hydration patterns or importing hydration utilities breaks the optimizer and negates performance gains.
2. Server-Only Import Leakage: Directly importing database clients or Node modules in Qwik components. These must be wrapped in server$ functions to guarantee server-only execution and prevent client-side bundling.
3. Third-Party Library Incompatibility: Using React-specific libraries (e.g., React Query, Framer Motion) without Qwik alternatives. Leads to runtime errors or broken serialization. Use Qwik-native wrappers or apply $ syntax for lazy-loading compatibility.
4. State Management Mismatch: Porting useState/useReducer directly. Qwik requires useSignal/createStore for fine-grained reactivity. Direct ports cause unnecessary component re-renders and break resumability serialization.
5. Routing Structure Misalignment: Ignoring Qwik City's file-based routing conventions. Incorrect route mapping causes 404s or broken navigation. Dynamic routes must follow [param].tsx and nested layouts must use layout.tsx correctly.
6. Testing Utility Neglect: Using React Testing Library instead of @builder.io/qwik/testing. Results in false positives/negatives due to different rendering lifecycles, serialization expectations, and event handler lazy-loading behavior.

Deliverables

• Migration Blueprint: Architectural mapping guide detailing RSC-to-Qwik component conversion patterns, state management equivalents, data fetching strategies, and routing transformations. Includes decision trees for incremental vs. full migration paths.
• Pre/Post-Migration Checklist:
  • Audit RSC-specific features and classify components (server/client/shared)
  • Inventory third-party dependencies and verify Qwik compatibility
  • Baseline Core Web Vitals (LCP, INP, CLS, TTI)
  • Replace hydration-dependent patterns with resumable equivalents
  • Validate server-only execution boundaries (server$)
  • Run Qwik optimizer and configure route prefetching
  • Execute integration tests with @builder.io/qwik/testing
• Configuration Templates:
  • vite.config.ts optimized for Qwik City SSR/SSG
  • server$ wrapper template for database/API isolation
  • routeLoader$ data-fetching boilerplate with error handling
  • Testing setup configuration for component serialization validation