Workflow migracji frameworków w Cursor

Twoja aplikacja React używa komponentów klasowych, Redux z connect(), React Router v5 i niestandardowego builda Webpack. Zespół chce przejść na komponenty funkcyjne z hookami, Zustand do zarządzania stanem, React Router v7 i Vite. Jest 180 komponentów, 45 kontenerów podłączonych do Redux i 30 definicji tras. Pełny rewrite zajmie miesiące i zatrzyma rozwój nowych funkcji. Stopniowa migracja pozwala dalej dostarczać funkcjonalności podczas modernizacji — ale potrzebujesz systematycznego podejścia, aby nie skończyć z bazą kodu, która na zawsze jest w połowie starych wzorców i w połowie nowych.

Migracje frameworków to jeden z najsilniejszych przypadków użycia Cursor. Transformacje są mechaniczne (konwersja składni klas na funkcje, zamiana jednego API na inne), wzorce są dobrze udokumentowane, a wolumen jest na tyle duży, że wsparcie AI zwraca się wielokrotnie. Wyzwanie nie polega na pojedynczej transformacji — polega na orkiestracji 180 takich transformacji bez psucia czegokolwiek.

Co wyniesiesz z tej lekcji

• Workflow planowania, który mapuje zakres migracji przed zmianą jakiegokolwiek kodu
• Prompty do automatycznej transformacji plik po pliku z walidacją
• Strategia strangler fig, która pozwala migrować przyrostowo bez “wielkiego wybuchu”
• Techniki obsługi najtrudniejszych migracji (zarządzanie stanem, routing, narzędzia budowania)
• Reguły projektu, które zapobiegają mieszaniu starych i nowych wzorców w nowym kodzie

Planowanie migracji

Każda migracja zaczyna się od inwentaryzacji. Musisz wiedzieć dokładnie, co migrujesz, ile plików jest dotkniętych i jakie transformacje są potrzebne. Tryb Plan jest do tego stworzony.

Wskazówka

Prompt do skopiowania — Planowanie migracji:

@src

I need to migrate this React application:

FROM:
- Class components with lifecycle methods
- Redux with connect() HOC and mapStateToProps/mapDispatchToProps
- React Router v5 (Switch, Route with component prop)
- Webpack 4 build with custom config

TO:
- Functional components with hooks (useState, useEffect, useCallback, useMemo)
- Zustand for state management
- React Router v7 with data loaders
- Vite with TypeScript

Create a migration plan:
1. Scan the codebase and count: class components, connected components, route definitions
2. Categorize by complexity: simple (stateless), medium (lifecycle methods), complex (HOCs, render props)
3. Identify dependencies between migrations (which must happen first?)
4. Propose a migration order that minimizes risk
5. Identify files that can be auto-migrated vs those needing manual attention

Ask clarifying questions about our specific patterns before finalizing.

Tryb Plan przeskanuje twoją bazę kodu i wyprodukuje ustrukturyzowany podział. Typowy wynik może wyglądać tak:

• 95 prostych komponentów klasowych (bez stanu, bez lifecycle) — migracja automatyczna
• 50 średnich komponentów (stan i componentDidMount) — półautomatyczne
• 35 złożonych komponentów (wiele lifecycle methods, shouldComponentUpdate) — wymaga przeglądu
• 45 komponentów podłączonych do Redux — zależy od migracji Zustand
• 30 definicji tras — migracja wsadowa po komponentach

Ta inwentaryzacja staje się twoją mapą drogową migracji.

Wzorzec Strangler Fig

Najbezpieczniejsza strategia migracji to strangler fig: nowy kod używa nowych wzorców, stary kod jest migrowany przyrostowo, a oba współistnieją do ukończenia migracji. Reguły projektu Cursor egzekwują tę granicę.

.cursor/rules/migration.md

# Reguły migracji (aktywne)

## Nowy kod
- Wszystkie nowe komponenty MUSZĄ być komponentami funkcyjnymi z hookami
- Całe nowe zarządzanie stanem MUSI używać store'ów Zustand
- Wszystkie nowe trasy MUSZĄ używać wzorca data loader z React Router v7
- Nowy kod nie może używać: komponentów klasowych, Redux connect(), React Router v5 Switch

## Współistnienie
- Stare komponenty klasowe mogą importować nowe hooki przez funkcje wrapper
- Stare komponenty podłączone do Redux mogą czytać ze store'ów Zustand przez bridge
- Oba systemy routingu działają jednocześnie przez warstwę kompatybilności

## Status migracji
- Komponenty: 45/180 zmigrowanych (25%)
- Store'y Redux: 2/8 zmigrowanych (25%)
- Trasy: 0/30 zmigrowanych (0%)

Aktualizuj status migracji w tym pliku reguł w miarę postępów. Agent czyta go przy każdej interakcji, więc zawsze zna aktualny stan migracji.

Migracja komponentów

Proste komponenty (bezstanowe)

Najłatwiejsza migracja: komponenty klasowe bez stanu i bez lifecycle methods.

Wskazówka

Prompt do skopiowania — Wsadowa migracja prostych komponentów:

@src/components/Button.tsx

Migrate this class component to a functional component:

1. Convert class to function component with TypeScript props interface
2. Replace render() with a direct return
3. Replace this.props with destructured props
4. Remove the class import (Component from 'react')
5. Keep the same export pattern (named export, not default)
6. Preserve all existing JSX, className, and event handler logic exactly

Do not change any behavior. The component must render identically before and after.
Run the existing tests to verify nothing broke.

Do migracji wsadowej możesz przetwarzać wiele plików naraz:

Migrate these 5 stateless class components to functional components.
Apply the same transformation to each:

@src/components/Badge.tsx
@src/components/Card.tsx
@src/components/Divider.tsx
@src/components/Icon.tsx
@src/components/Label.tsx

For each file: convert class to function, destructure props, preserve behavior exactly.
After migration, run "npm run type-check" to verify TypeScript compilation.

Średnie komponenty (lifecycle methods)

Komponenty ze stanem i lifecycle methods wymagają ostrożniejszej transformacji:

Wskazówka

Prompt do skopiowania — migracja komponentu naszpikowanego lifecycle methods:

@src/components/UserProfile.tsx

Migrate this class component to a functional component:

1. componentDidMount -> useEffect with empty dependency array
2. componentDidUpdate(prevProps) -> useEffect with dependency on the specific props
3. componentWillUnmount -> useEffect cleanup function
4. this.state + this.setState -> useState hooks (one per state variable)
5. Instance methods -> useCallback where used as event handlers
6. getDerivedStateFromProps -> compute during render or useMemo

Map each lifecycle method to its hook equivalent. Show the before/after
for each transformation in comments so the reviewer understands the mapping.

Preserve the exact same component behavior. Pay attention to:
- State initialization that depends on props
- Cleanup logic (timers, subscriptions, event listeners)
- Conditional effects based on prop changes

Złożone komponenty (HOC-e, render props)

Złożone komponenty wymagają indywidualnej uwagi:

Wskazówka

Prompt do skopiowania — migracja komponentu connect() + HOC + render prop:

@src/containers/OrderDashboard.tsx @src/store/ordersReducer.ts

This component uses:
- connect() from react-redux with mapStateToProps and mapDispatchToProps
- withRouter() HOC from react-router-dom
- A render prop from <Query> component for data fetching

Migrate it step by step:
1. Replace connect() with a Zustand store hook (create the store if needed)
2. Replace withRouter() with useNavigate() and useParams() hooks
3. Replace the <Query> render prop with a React Query useQuery hook
4. Convert the class to a function component

Create the Zustand store at src/stores/orders.ts that replaces the Redux
ordersReducer. It should maintain the same state shape and actions.

Show the migration as a series of commits:
- Commit 1: Create Zustand store alongside Redux
- Commit 2: Convert component to functional with hooks
- Commit 3: Remove old Redux reducer and action files

Migracja zarządzania stanem

Migracja Redux do Zustand jest najwyższego ryzyka, ponieważ zarządzanie stanem dotyka każdego podłączonego komponentu. Migruj jeden store naraz.

Wskazówka

Prompt do skopiowania — Migracja store’u Redux do Zustand:

@src/store/cartReducer.ts @src/store/cartActions.ts @src/store/cartSelectors.ts

Migrate the cart Redux module to a Zustand store:

1. Create src/stores/cart.ts with Zustand:
   - Same state shape as the current reducer's initial state
   - Actions become store methods (addItem, removeItem, updateQuantity, clear)
   - Selectors become derived values or hook selectors
   - Include devtools middleware for debugging

2. Create a bridge at src/stores/bridges/cart-bridge.ts that:
   - Syncs Zustand cart state to Redux store (for components not yet migrated)
   - Lets both old (Redux-connected) and new (Zustand hook) components coexist
   - Will be removed once all cart consumers are migrated

3. Update one consumer component as a proof of concept:
   - Pick the simplest Redux-connected cart component
   - Replace connect() with useCartStore()
   - Verify it works alongside non-migrated components

List all files that still use the Redux cart store so I can track migration progress.

Migracja routingu

Migrację routera najlepiej przeprowadzić wsadowo, ponieważ trasy są od siebie zależne:

Wskazówka

Prompt do skopiowania — migracja React Router v5 do v7:

@src/routes @src/App.tsx

Migrate from React Router v5 to React Router v7:

1. Replace <Switch> with <Routes>
2. Replace <Route component={X}> with <Route element={<X />}>
3. Replace <Redirect> with <Navigate>
4. Replace useHistory() with useNavigate()
5. Replace match.params with useParams()
6. Replace useLocation().search parsing with useSearchParams()
7. Add data loaders for routes that fetch data on mount

Migration steps:
- First: Update App.tsx route definitions (batch change)
- Then: Update each component that uses routing hooks (one by one)
- Finally: Add data loaders to replace componentDidMount API calls

Keep the compatibility layer: if a route uses both old and new patterns
during migration, it should still work.

Migracja narzędzia budowania

Migracja Webpack do Vite jest zazwyczaj robiona w jednej sesji, ponieważ dotyczy tylko konfiguracji:

Wskazówka

Prompt do skopiowania — migracja Webpack 4 do Vite:

@webpack.config.js @babel.config.js @tsconfig.json @package.json

Migrate from Webpack 4 to Vite:

1. Create vite.config.ts with:
   - React plugin
   - TypeScript support
   - Path aliases matching our current webpack resolve.alias
   - Proxy configuration matching our current devServer.proxy
   - Environment variable handling (REACT_APP_ -> VITE_)

2. Update tsconfig.json:
   - Add Vite client types
   - Update module resolution if needed

3. Update import.meta.env usage:
   - Find all process.env.REACT_APP_ references
   - Replace with import.meta.env.VITE_
   - Create .env file with renamed variables

4. Update index.html:
   - Move from public/ to project root
   - Add module script tag for entry point

5. Update package.json scripts:
   - dev: vite
   - build: vite build
   - preview: vite preview

List any webpack plugins that need Vite equivalents.
Do NOT remove the webpack config yet -- keep it as fallback until verified.

Kiedy to się psuje

Agent migruje kod niepoprawnie, a testy przechodzą, ponieważ testy też są nieaktualne. To najgroźniejszy błąd migracji. Przed migracją komponentu zweryfikuj, że jego istniejące testy faktycznie testują zachowania, na których ci zależy. Poproś Agenta: “Przed migracją tego komponentu przejrzyj jego plik testowy. Czy testy pokrywają kluczowe zachowania, czy tylko sprawdzają, że się renderuje?”

Bridge migracyjny powoduje problemy z wydajnością. Synchronizacja stanu między Redux a Zustand przy każdej zmianie tworzy niepotrzebne re-rendery. Utrzymuj bridge prostym (synchronizacja jednokierunkowa) i usuń go, gdy tylko wszystkie konsumenci danego store’u będą zmigrowane.

Częściowo zmigrowany kod myli Agenta. Gdy twoja baza kodu ma zarówno stare, jak i nowe wzorce, Agent czasem generuje kod używając starego wzorca, ponieważ widzi więcej jego przykładów. Plik reguł migracji na początku tego artykułu temu zapobiega — ale tylko jeśli jest ustawiony na “Always Apply.”

Migracja zatrzymuje się na 80%. Ostatnie 20% komponentów jest zawsze najtrudniejsze, ponieważ to najbardziej złożone komponenty. Nie zostawiaj ich. Zaplanuj dedykowane sprinty migracyjne i użyj trybu Plan w Cursor, aby rozbić każdy złożony komponent na mniejsze, łatwiejsze do ogarnięcia kroki.

Potrzebny jest rollback po częściowej migracji. Zachowaj stare ścieżki kodu dostępne (zakomentowane lub za feature flagami) do czasu zweryfikowania migracji na produkcji. Checkpointy Cursor pomagają z rollbackami per sesja, ale dla wielodniowych migracji używaj gałęzi Git.

Co dalej

Projektowanie architektury Zaprojektuj architekturę docelową przed rozpoczęciem kolejnej migracji.

Testowanie i TDD Zbuduj kompleksowe testy do walidacji migracji.

Refaktoryzacja legacy Refaktoryzuj wzorce legacy code obok migracji frameworków.