---

name: tailwind-react-guidelines description: Frontend React 19 + TypeScript 5.7+ + TailwindCSS v4 + shadcn/ui dla Vite SPA. Komponenty, React Query, formularze (RHF + Zod), testowanie (Vitest + RTL + MSW), lazy loading, Suspense, Sonner. Używaj przy tworzeniu komponentów, stron, stylowaniu, data fetchingu, formularzach, testach, optymalizacji.

Tailwind React Guidelines

Cel

Przewodnik dla Vite + React 19 SPA - nowoczesny stack zgodny ze standardami 2025.

Kiedy Używać Tego Skilla

• Tworzenie nowych komponentów React
• Stylowanie z TailwindCSS v4 + shadcn/ui
• Data fetching z React Query
• Formularze z React Hook Form + Zod
• Testowanie z Vitest + React Testing Library + MSW
• Routing z React Router
• Obsługa błędów i loading states
• Optymalizacja wydajności

---

Quick Start Checklist

Nowy Komponent

• TypeScript interface dla props
• Funkcja (nie React.FC)
• Ref jako prop (nie forwardRef) - React 19
• Import aliasy: @/components, @/lib, @/hooks
• TailwindCSS utility classes
• Default export na dole (dla lazy loading)

Memoizacja

• Z React Compiler: Nie używaj useCallback/useMemo - Compiler optymalizuje automatycznie
• Bez React Compiler: useCallback tylko gdy przekazujesz handler do memo() child

Data Fetching

• React Query (useQuery, useMutation) - nie useEffect
• Early returns: loading → error → empty → data
• toast.promise() dla feedback użytkownika

Formularze

• React Hook Form + Zod (zodResolver)
• aria-invalid i aria-describedby dla a11y
• useMutation dla submit

Nowa Strona

• Lazy load: const Page = lazy(() => import('@/pages/Page'))
• Suspense wrapper z fallback
• Error Boundary (react-error-boundary)
• Route w App.tsx

---

Import Aliasy

Zdefiniowane w: vite.config.ts i tsconfig.json

---

Topic Guides

Wzorce Komponentów

React 19 patterns, ref jako prop (nie forwardRef), Error Boundaries z react-error-boundary. Pełny przewodnik: resources/component-patterns.md

---

Stylowanie z TailwindCSS

Tailwind v4 (CSS-first config z @theme), OKLCH colors, container queries, shadcn/ui, cn() dla kompozycji. Pełny przewodnik: resources/styling-guide.md

---

Organizacja Plików i Routing

Copysrc/
  components/
    ui/              # shadcn/ui primitives
    [Feature].tsx    # Komponenty aplikacji
  pages/             # Route-level components
  hooks/             # React Query hooks
  lib/               # api.ts, utils.ts, queryClient.ts
  types/             # TypeScript types
  test/              # Setup, utils, mocks

Protected routes, useSearchParams, nested routes. Pełny przewodnik: resources/file-organization.md

---

Formularze

React Hook Form + Zod, walidacja client-side, kontrolowane komponenty, multi-step wizardy, upload plików. Pełny przewodnik: resources/forms.md

---

Stany Ładowania i Błędów

Suspense dla lazy-loaded components:

Copy<Suspense fallback={<LoadingOverlay />}>
    <LazyComponent />
</Suspense>

Early returns dla data fetching (React Query):

Copyconst { data, isLoading, error } = useTemplates();

if (isLoading) return <Skeleton />;
if (error) return <ErrorMessage error={error} />;
if (!data?.length) return <EmptyState />;

return <TemplateList data={data} />;

Pełny przewodnik: resources/loading-and-error-states.md

---

Testowanie

Vitest + React Testing Library + MSW v2. Testy komponentów, hooków React Query, formularzy, a11y. Pełny przewodnik: resources/testing.md

---

Wydajność

React Compiler (opcjonalny), React Query caching, useTransition, useOptimistic, lazy loading. Pełny przewodnik: resources/performance.md

---

TypeScript Standards

Strict mode, moduleResolution: "bundler", inline type imports, satisfies operator, Zod dla runtime validation. Pełny przewodnik: resources/typescript-standards.md

---

Główne Zasady 2025

1. React Query dla data fetchingu - nie useEffect
2. React Hook Form + Zod dla formularzy - nie useState dla każdego pola
3. Memoizacja warunkowa - z React Compiler: żadna; bez: tylko dla memo children
4. Suspense dla lazy components - nie dla data (React Query obsługuje)
5. Tailwind v4 - konfiguracja w CSS (@theme), OKLCH colors
6. TypeScript strict - no any, Zod dla runtime validation
7. Error Boundaries - react-error-boundary dla unexpected errors
8. Sonner dla toasts - toast.success(), toast.promise()
9. Vitest + RTL + MSW dla testów - behavioral testing, MemoryRouter
10. Logger dla błędów - logger.error() (production-safe)

---

Navigation Guide