qwik

qwik Best Practices

Qwik is an edge-first framework built on resumability, not hydration. This means your application's JavaScript is only loaded and executed when absolutely necessary, leading to instant Time-To-Interactive (TTI). Our guidelines prioritize this core principle.

Critical Guidelines:

1. Define Every UI Piece with component$

All interactive UI components must be wrapped in component$. This is Qwik's fundamental primitive for enabling automatic code-splitting and lazy loading.

❌ BAD: Regular function component

// my-button.tsx
export const MyButton = () => { // Missing '$'
  return <button onClick={() => alert('Clicked!')}>Click me</button>;
};

✅ GOOD: component$ for resumability

// my-button.tsx
import { component$ } from '@builder.io/qwik';

export const MyButton = component$(() => {
  return <button onClick$={() => alert('Clicked!')}>Click me</button>; // onClick$ is also a QRL
});

2. Use useStore for Reactive State

Manage component-local reactive state using useStore. This ensures state is serializable and resumable across server-side rendering and client-side interactions. Always type your stores for clarity and safety.

❌ BAD: Non-reactive or non-serializable state

// counter.tsx
import { component$ } from '@builder.io/qwik';

export const Counter = component$(() => {
  let count = 0; // Not reactive, won't persist across renders/resumability
  const increment = () => { count++; };
  return <button onClick$={increment}>{count}</button>;
});

✅ GOOD: useStore with TypeScript interface

// counter.tsx
import { component$, useStore } from '@builder.io/qwik';

interface CounterStore {
  count: number;
}

export const Counter = component$(() => {
  const store = useStore<CounterStore>({ count: 0 });
  return (
    <button onClick$={() => store.count++}>
      Count: {store.count}
    </button>
  );
});

3. Defer Client-Side Effects with useVisibleTask$