tanstack-router-migration

Migrate React applications from React Router to TanStack Router with file-based routing. Use when user requests: (1) Router migration, (2) TanStack Router setup, (3) File-based routing implementation, (4) React Router replacement, (5) Type-safe routing, or mentions 'migrate router', 'tanstack router', 'file-based routes'.

1. Zainstaluj zależności core: bun add @tanstack/react-router @tanstack/zod-adapter oraz wtyczkę budowania dla Twojego bundlera: bun add -d @tanstack/router-plugin. Opcjonalnie dodaj integracje takie jak nuqs do zarządzania stanem URL lub @sentry/react do śledzenia błędów.

2. Przeprowadź audyt istniejącego kodu React Router, szukając wszystkich importów i użyć hooków: grep -r "from 'react-router" src/ --include="*.tsx" --include="*.ts" oraz grep -r "useParams\|useSearchParams\|useNavigate" src/ --include="*.tsx" --include="*.ts".

3. Skonfiguruj wtyczkę budowania w pliku konfiguracyjnym Twojego bundlera (Vite, Webpack itp.) przed utworzeniem tras.

4. Utwórz strukturę routingu opartą na plikach w katalogu src/routes/. Każdy plik reprezentuje trasę, a struktura katalogów mapuje się na hierarchię routingu.

5. Podczas migracji hooków zawsze używaj parametru from dla bezpieczeństwa typów: useParams({ from: '/path' }). Waliduj parametry wyszukiwania za pomocą schematów Zod i adaptera @tanstack/zod-adapter. Dla opcjonalnych parametrów wyszukiwania używaj wrappera fallback().

6. Zarejestruj typ routera w Twojej aplikacji, aby włączyć pełną inferencję TypeScript. Nigdy nie edytuj automatycznie generowanego pliku routeTree.gen.ts i nie mieszaj hooków React Router z nowym kodem podczas migracji.