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

src/
  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:

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

Early returns dla data fetching (React Query):

const { 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