Dlaczego migracja Vue 2 nadal jest problemem biznesowym
Vue 2 przestało otrzymywać oficjalne poprawki z końcem 2023 roku. Sama data zakończenia wsparcia nie zatrzymuje aplikacji: system może nadal obsługiwać klientów i generować przychód. Problem pojawia się stopniowo. Coraz trudniej aktualizować biblioteki, usuwać podatności, zatrudniać osoby chętne do pracy ze starym stosem i rozwijać produkt w tempie oczekiwanym przez biznes.
Koszt pozostania przy Vue 2 rzadko występuje w budżecie jako osobna pozycja. Widać go w dłuższych estymacjach, poprawkach po wdrożeniu, blokadach przy aktualizacji narzędzi oraz funkcjach odkładanych dlatego, że dotykają zbyt kruchej części systemu. Z czasem każdy większy rozwój zaczyna zawierać ukryty podatek od długu technologicznego.
Migracji nie warto jednak uzasadniać wyłącznie komunikatem „framework jest stary”. Dobra decyzja łączy stan technologii z planem produktu: wymaganiami bezpieczeństwa, kosztami utrzymania, dostępnością zespołu i funkcjami przewidzianymi na kolejne kwartały.
Kiedy migracja rzeczywiście jest potrzebna
Migracja staje się pilna, gdy przestarzały frontend blokuje istotne decyzje biznesowe. Typowe sygnały to brak wspieranych wersji kluczowych bibliotek, podatności bez dostępnej ścieżki aktualizacji, problemy z nowymi wersjami Node.js lub narzędzi budujących, a także częste regresje przy pozornie niewielkich zmianach.
Silnym argumentem jest również planowany rozwój produktu. Jeżeli firma chce przebudować główne procesy, wprowadzić nowy design system, poprawić wydajność albo rozbudować zespół, dalsze inwestowanie w rozwiązania specyficzne dla Vue 2 może zwiększać przyszły koszt przejścia.
Nie każda aplikacja wymaga natychmiastowej migracji. Stabilny, wewnętrzny system o ograniczonym dostępie i krótkim pozostałym cyklu życia może potrzebować przede wszystkim monitoringu, kontroli zależności i planu wycofania. Decyzję należy podjąć po audycie, a nie na podstawie samego numeru wersji.
Audyt obecnej aplikacji
Audyt ma odpowiedzieć na dwa pytania: co technicznie blokuje Vue 3 oraz które fragmenty produktu są zbyt ważne, by migrować je bez dodatkowych zabezpieczeń. Sam raport z npm outdated nie wystarczy.
Wersje Vue i bibliotek
Najpierw ustalamy dokładną wersję Vue, sposób budowania projektu, wersję Node.js oraz pełne drzewo zależności. Sprawdzamy, które pakiety mają wersje zgodne z Vue 3, które zmieniły API, a które są porzucone. Szczególnej uwagi wymagają biblioteki używane w wielu ekranach: formularze, walidacja, tabele, wykresy, edytory tekstu, obsługa dat i internacjonalizacja.
Warto odróżnić zależności rzeczywiście używane od pozostałości w package.json. Usunięcie martwych pakietów przed migracją zmniejsza liczbę fałszywych problemów i upraszcza późniejsze aktualizacje.
Vuex i zarządzanie stanem
Inwentaryzujemy moduły Vuex, pluginy, persystencję stanu oraz miejsca, w których komponenty bezpośrednio polegają na strukturze store. Nie trzeba automatycznie przechodzić na Pinię w tej samej chwili co na Vue 3. Czasem bezpieczniej najpierw uruchomić obecną logikę na wspieranej wersji Vuex, a zmianę modelu stanu wykonać w kolejnym etapie.
Vue Router
Sprawdzamy definicje tras, guardy, lazy loading, zagnieżdżone widoki, przekierowania i zależności od history mode. Zmiany w Vue Router 4 są zwykle przewidywalne, lecz błędy w guardach mogą dotknąć logowania, uprawnień i powrotu użytkownika do rozpoczętego procesu.
Biblioteki UI
Vuetify, BootstrapVue, Element UI i własne zestawy komponentów mają różne ścieżki przejścia. Aktualizacja biblioteki UI potrafi być większym projektem niż aktualizacja samego Vue, ponieważ zmienia markup, właściwości komponentów i wygląd setek ekranów. Audyt powinien oszacować liczbę użyć oraz wskazać komponenty bez odpowiedników.
Własne pluginy i dyrektywy
Globalne mixiny, filtry, dyrektywy, modyfikacje prototypu i pluginy korzystające z wewnętrznych mechanizmów Vue często skupiają największe ryzyko. Dla każdego z nich ustalamy właściciela, zakres użycia i możliwy odpowiednik w Vue 3. Niewielki plugin używany w całym produkcie może być ważniejszy niż duży, izolowany moduł.
Testy
Liczymy nie tylko testy, lecz również to, co faktycznie chronią. Testy jednostkowe komponentów oparte na szczegółach implementacji mogą wymagać przepisania, zanim pomogą w migracji. Większą wartość na początku dają testy krytycznych przepływów: logowania, płatności, zapisu formularza, uprawnień czy eksportu danych.
SSR i Nuxt
Aplikacje z Nuxtem wymagają osobnej analizy. Przejście z Nuxt 2 do Nuxt 3 dotyka renderowania, routingu, pobierania danych, middleware, modułów, konfiguracji serwera i wdrożenia. Trzeba też sprawdzić hydratację, cache, SEO oraz kod zakładający dostęp do window lub document.
Integracje i zależności zewnętrzne
Mapujemy API, system logowania, płatności, analitykę, monitoring błędów, mapy, osadzone widgety i proces wdrożeniowy. Migracja może nie zmieniać kontraktu backendu, ale łatwo przypadkowo zmienić format daty, kolejność wywołań albo obsługę błędu, na której polega proces biznesowy.
Rezultatem audytu powinien być rejestr ryzyk, mapa zależności, rekomendowana strategia i plan weryfikacji. Dopiero na tej podstawie warto estymować projekt.
Strategie migracji
Nie istnieje jedna strategia dobra dla wszystkich aplikacji. Wybór zależy od możliwości dzielenia systemu, jakości testów, tempa rozwoju produktu i tolerancji firmy na równoległe utrzymywanie dwóch sposobów pracy.
Migracja etapowa
Kod jest dostosowywany seriami, a aplikacja pozostaje używalna po każdym etapie. Najpierw usuwa się niezgodne wzorce i aktualizuje zależności, później komponenty oraz infrastrukturę. To zwykle najlepsza opcja dla aktywnie rozwijanego produktu, ponieważ pozwala regularnie wdrażać zmiany i szybko wykrywać błędne założenia.
Kosztem jest okres przejściowy: zespół musi pilnować reguł dla starego i nowego kodu oraz powstrzymywać dopisywanie kolejnego długu w migrowanych obszarach.
Compatibility build
@vue/compat uruchamia aplikację Vue 2 w środowisku Vue 3 i raportuje niezgodne zachowania. Dobrze działa jako narzędzie przejściowe, gdy większość kodu jest bliska kompatybilności. Nie jest docelową architekturą ani sposobem na bezterminowe pozostawienie ostrzeżeń.
Przed wyborem compatibility build trzeba potwierdzić, że kluczowe biblioteki mogą działać w tym trybie. Jedna zależność oparta na prywatnym API Vue może zablokować pozornie prostą ścieżkę.
Wydzielanie modułów
Jeśli aplikacja ma wyraźne granice domenowe, można przenosić całe moduły: na przykład panel raportów, ustawienia konta lub nowy proces zamówienia. Granicą może być routing, osobny bundle albo uzgodniony kontrakt komponentu.
Takie podejście ogranicza powierzchnię regresji, ale wymaga świadomego rozwiązania współdzielonego stanu, nawigacji, stylów i uwierzytelniania. Bez wyraźnego kontraktu dwa światy szybko zaczynają się przenikać.
Pełne przejście
Jednorazowe przejście całej aplikacji ma sens dla mniejszych, dobrze przetestowanych produktów albo wtedy, gdy utrzymywanie warstwy kompatybilności byłoby bardziej ryzykowne niż krótki okres zamrożenia zmian. Nadal należy dzielić pracę na techniczne kamienie milowe i integrować ją regularnie, nawet jeśli finalne przełączenie nastąpi jednego dnia.
Kiedy rewrite nie ma sensu
Przepisanie aplikacji od zera brzmi atrakcyjnie, bo usuwa ograniczenia starego kodu. W praktyce stary system zawiera lata nieudokumentowanych reguł biznesowych i obsłużonych przypadków brzegowych. Rewrite odtwarza je bez korzyści dla użytkownika, a przez długi czas firma finansuje dwa produkty.
Pełne przepisanie warto rozważyć, gdy zmienia się nie tylko framework, ale też model produktu, architektura i większość interfejsu, a istniejącego kodu nie da się wiarygodnie testować ani dzielić. Nie powinno być domyślną odpowiedzią na nieestetyczny kod.
Najczęstsze ryzyka
Największym ryzykiem jest nieznany zakres. Pojedyncze komponenty zwykle migrują się łatwo; problemy tworzą zależności między nimi, globalne zachowania i biblioteki bez następcy. Dlatego estymacja przed audytem bywa pozornie precyzyjna.
Drugim ryzykiem jest łączenie zbyt wielu zmian. Jednoczesna migracja do Vue 3, wymiana UI, przejście z Vuex na Pinię, zmiana API i redesign utrudniają ustalenie źródła regresji. Zmiany mogą należeć do jednego programu modernizacji, lecz powinny mieć osobne kryteria akceptacji.
Pozostałe częste problemy to:
- niedziałające pluginy i brak utrzymywanych zamienników,
- różnice w reaktywności ujawniające ukryte założenia kodu,
- zmiany w cyklu życia komponentów i kolejności efektów,
- regresje wizualne po aktualizacji biblioteki UI,
- problemy z SSR i hydratacją,
- niedoszacowane testy ręczne krytycznych procesów,
- długa gałąź migracyjna, której nie da się bezpiecznie połączyć z bieżącym rozwojem,
- brak osoby biznesowej zdolnej rozstrzygać, które zachowanie jest prawidłowe.
Rejestr ryzyk powinien mieć właścicieli i działania ograniczające, nie być tylko dodatkiem do prezentacji startowej.
Jak przygotować testy i ograniczyć regresje
Przed zmianą frameworka warto zabezpieczyć zachowanie, a nie szczegóły implementacji. Zaczynamy od listy procesów, których awaria wpływa na przychód, dane, zgodność lub obsługę klienta. Dla każdego zapisujemy oczekiwany rezultat i najważniejsze warianty.
Testy end-to-end powinny obejmować kilka krytycznych ścieżek od początku do końca. Testy integracyjne dobrze chronią formularze, store, routing i komunikację z API. Testy jednostkowe zostawiamy dla logiki, którą można odseparować od frameworka. Nie ma potrzeby osiągania arbitralnego procentu pokrycia przed startem.
Przydatne są również:
- zrzuty referencyjne najważniejszych ekranów i kontrola regresji wizualnych,
- środowisko staging możliwie podobne do produkcji,
- obserwowalność błędów frontendu i kluczowych zdarzeń biznesowych,
- feature flags dla obszarów przełączanych etapowo,
- krótka lista testów eksploracyjnych wykonywana przed każdym wdrożeniem,
- plan wycofania wersji bez konieczności odwracania migracji w pośpiechu.
Testy nie eliminują ryzyka. Skracają czas między wprowadzeniem błędu a jego wykryciem i pozwalają podejmować mniejsze decyzje wdrożeniowe.
Etapy przykładowego projektu migracyjnego
- Rozpoznanie i audyt. Zbieramy wersje, zależności, architekturę, krytyczne procesy oraz ograniczenia wdrożenia. Uruchamiamy aplikację lokalnie i weryfikujemy, czy obecny proces budowania jest powtarzalny.
- Proof of concept. Migrujemy reprezentatywny fragment: nie najłatwiejszy ekran, lecz taki, który dotyka routingu, stanu, UI i API. Dzięki temu sprawdzamy najważniejsze założenia przed pełną estymacją.
- Przygotowanie fundamentów. Aktualizujemy narzędzia, usuwamy martwe zależności, ustalamy reguły kodu i dokładamy brakujące testy krytyczne. Jeśli używamy
@vue/compat, definiujemy warunki jego usunięcia. - Migracja właściwa. Przenosimy moduły lub grupy komponentów w kolejności wynikającej z zależności. Każdy etap ma mierzalne kryteria ukończenia i może być zweryfikowany na stagingu.
- Stabilizacja. Usuwamy ostrzeżenia kompatybilności, wykonujemy testy regresji, poprawiamy wydajność i sprawdzamy monitoring. Nie odkładamy znanych błędów jako „porządków po migracji”, jeśli wpływają na działanie produktu.
- Wdrożenie i obserwacja. Wybieramy okno wdrożenia, ustalamy odpowiedzialność zespołu i obserwujemy błędy oraz kluczowe procesy. Po stabilizacji porządkujemy dokumentację i planujemy kolejne modernizacje osobno.
Co wpływa na czas realizacji
Liczba komponentów jest tylko jednym z parametrów. Większe znaczenie może mieć liczba nietypowych pluginów, skala biblioteki UI, jakość granic między modułami oraz możliwość automatycznego potwierdzenia, że zachowanie się nie zmieniło.
Na harmonogram wpływają przede wszystkim:
- stan i dostępność zależności dla Vue 3,
- Nuxt, SSR i niestandardowa infrastruktura wdrożeniowa,
- wielkość oraz spójność Vuex,
- liczba globalnych mixinów, filtrów i dyrektyw,
- zakres testów automatycznych i pracy QA,
- równoległy rozwój funkcji w tych samych plikach,
- dostępność osób znających reguły biznesowe,
- wymagane okresy akceptacji i okna wdrożeniowe.
Mały, uporządkowany produkt może przejść migrację w ciągu kilku tygodni. Rozbudowany system z SSR, własnym UI i słabymi testami może wymagać wielu miesięcy etapowej pracy. To orientacyjne skale, nie obietnica terminu; wiarygodny plan powstaje po audycie i próbie na reprezentatywnym module.
Co wpływa na koszt
Koszt wynika z czasu zespołu, ale nie tylko z pracy nad komponentami. Obejmuje analizę, przygotowanie testów, QA, poprawki integracji, środowiska, wdrożenie i stabilizację. Tańsza estymacja pomijająca te elementy nie usuwa kosztu — przenosi go na okres po publikacji.
Największe pozycje kosztowe to zwykle wymiana biblioteki UI, migracja Nuxt/SSR, zastąpienie porzuconych zależności, uporządkowanie globalnego stanu oraz ręczna weryfikacja dużej liczby procesów. Na budżet wpływa też model współpracy: stały zakres wymaga wcześniejszego ograniczenia niepewności, natomiast praca etapowa pozwala korygować plan po każdym odkryciu.
Nie podajemy ceny na podstawie liczby ekranów lub repozytorium bez uruchomienia aplikacji. Dokładna wycena wymaga audytu. Po nim można oddzielić zakres konieczny do bezpiecznego przejścia od usprawnień, które warto zaplanować jako kolejne etapy.
Checklista przed rozpoczęciem
- [ ] Znamy dokładne wersje Vue, Node.js, narzędzia budujące i zależności.
- [ ] Wiemy, które biblioteki nie mają zgodnej lub utrzymywanej wersji.
- [ ] Mamy mapę Vuex, routingu, pluginów, dyrektyw i globalnych mixinów.
- [ ] Osobno oceniliśmy bibliotekę UI oraz wpływ zmian wizualnych.
- [ ] Sprawdziliśmy SSR, Nuxt, hydratację i sposób wdrożenia.
- [ ] Zidentyfikowaliśmy krytyczne procesy biznesowe i ich właścicieli.
- [ ] Najważniejsze procesy mają test automatyczny albo powtarzalny scenariusz QA.
- [ ] Wybraliśmy reprezentatywny moduł do proof of concept.
- [ ] Ustaliliśmy strategię pracy równoległej z bieżącym rozwojem.
- [ ] Każdy etap ma kryteria akceptacji, monitoring i plan wycofania.
- [ ] Wiemy, które usprawnienia nie należą do samej migracji.
- [ ] Estymacja zawiera stabilizację, QA i wdrożenie, nie tylko zmianę kodu.
Podsumowanie
Udana migracja Vue 2 do Vue 3 nie zaczyna się od masowej zamiany składni. Zaczyna się od zrozumienia zależności, krytycznych procesów i powodów biznesowych. Najbezpieczniejszy plan dzieli pracę na sprawdzalne etapy, ogranicza liczbę jednoczesnych zmian i daje zespołowi możliwość regularnego wdrażania.
Jeśli nie wiesz, czy lepszy będzie compatibility build, migracja modułowa czy pełne przejście, pierwszym krokiem powinien być krótki audyt zakończony konkretną rekomendacją — również wtedy, gdy rekomendacją jest odłożenie migracji.
Modernizacja aplikacji