tanstack-router-migration

Umiejętność wspomagająca migrację projektów React z React Router na TanStack Router. Oferuje strukturalne podejście do zarówno przyrostowych, jak i czystych migracji. Automatycznie konfiguruje routing oparty na plikach w katalogu src/routes/, zapewnia bezpieczeństwo typów poprzez parametr from w hookach, waliduje parametry wyszukiwania za pomocą schematów Zod oraz integruje się z narzędziami budowania. Wspiera pełną inferencję TypeScript i opcjonalne integracje z zarządzaniem stanem URL oraz śledzeniem błędów.

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.