Przenoszenie aplikacji Angular z Webpack Builder do @angular/build

Przez lata projekty Angular budowano za pomocą Webpacka poprzez @angular-devkit/build-angular. Domyślnym narzędziem CLI jest obecnie buder application oparty na esbuild z pakietu @angular/build, a budery Webpacka są w procesie wycofywania: zgodnie z notatkami o wersji Angular 22, opublikowanymi w momencie pisania tego tekstu, buder oparty na Webpacku został oficjalnie uznany za przestarzały. Poniższe kroki pokazują, jak przenieść istniejące aplikacje na nowy buder, jakie zmiany zachodzą w pliku angular.json, co robić z dostosowanymi ładowaczami Webpacka oraz jak przygotować konfigurację TypeScript do użycia z natywnym kompilatorem Go.

Dlaczego ta zmiana jest teraz ważna

Poza kwestią wycofywania się z użycia istnieje również motywacja związana z wydajnością. TypeScript 7.0, wersja kompilatora przeniesiona na język Go pod nazwą TSGo lub Project Corsa, znajdował się w fazie kandydata na wersję końcową w momencie pisania tego tekstu i jest reklamowany jako aż 10 razy szybszy od kompilatora opartego na JavaScript. Plan rozwoju Angular zakłada dalszą rozbudowę tego kompilatora, a inwestycje w narzędzia skupiają się na pipeline’ach esbuild i Vite zamiast na Webpacku. Projekty używające Webpacka nie skorzystają z tych korzyści. Traktuj te terminy jako ważne i sprawdzaj najnowsze ogłoszenia.

Nowy narzędzie budujące ułatwia również organizację struktury plików. W konfiguracji Webpacka potrzebne były oddzielne narzędzia do tworzenia plików dla przeglądarki, serwera oraz do wstępnego renderowania; narzędzie application generuje je wszystkie z jednego źródła.

Krok 1: zamień narzędzie budujące w angular.json

Otwórz plik angular.json, znajdź element build swojego projektu oraz zlokalizuj narzędzie do budowania dla starszych przeglądarek:

// DELETE the legacy Webpack builder
"build": {
  "builder": "@angular-devkit/build-angular:browser",
  "options": { ... }
}

Zamień nazwę tego narzędzia na zjednoczone narzędzie do budowania aplikacji, tymczasowo zachowując obiekt z opcjami:

// MIGRATE to the unified esbuild application builder
"build": {
  "builder": "@angular/build:application",
  "options": { ... }
}

Nowsze wersje CLI oferują również automatyczną migrację za pomocą polecenia ng update, które przeprowadza te zmiany oraz inne modyfikacje opcji; sprawdź dokumentację Angulara w celu znalezienia dokładnego polecenia dla swojej wersji, a następnie przejrzyj wygenerowany raport różnic.

Krok 2: dostosowanie opcji budowania

Narzędzie application sprawdza swoje opcje w sposób bardziej rygorystyczny, dlatego kilka pozycji w build.options wymaga uwagi.

• Zmień nazwę main na browser. Punkt wejścia klienta jest teraz konfigurowany z użyciem opcji browser; main nie jest już akceptowany.
• Decyduj o układzie plików wyjściowych. Przy zwykłym łańcuchu tekstu, takim jak "outputPath": "dist/app", narzędzie tworzy wewnątrz niego podkatalogi browser i server. Skrypty部署, które oczekują plików bezpośrednio w dist/app, przestaną działać. Aby uzyskać prosty plik wyjściowy dla klienta, użyj formy obiektu i ustaw browser na pusty łańcuch tekstu:

"outputPath": {   "base": "dist/app",   "browser": "" }

• Zintegruj SSR z tym samym celem. Jeśli aplikacja wykorzystuje renderowanie po stronie serwera, usuń oddzielny cel architektoniczny server i przenieś punkt wejścia serwera do opcji budowniczego aplikacji, umożliwiając w ten sposób przedrenderowanie tam w razie potrzeby:

"server": "src/main.server.ts", "prerender": true

Następnie uruchom budowę w środowisku produkcyjnym i porównaj wynik z tym, czego oczekuje serwer lub CDN.

Krok 3: zastąpienie dostosowanych loaderów Webpacka

Najbardziej dotknięte są projekty, które rozszerzają proces budowy za pomocą @angular-builders/custom-webpack: każdy dostosowany loader, taki jak importy surowych plików SVG lub transformator Markdown, przestaje działać w momencie, gdy Webpack opuszcza łańcuch przetwarzania. Istnieją dwa rozwiązania:

• Zasoby takie jak SVG-y: mogą polegać na wbudowanej konfiguracji assets Angulara lub być odwoływane z plików CSS zamiast importowanych za pomocą loadera.

Spersonalizowane transformacje: wdroż je ponownie jako plugin esbuild i zarejestruj go za pomocą @angular-builders/custom-esbuild.

Najpierw zidentyfikuj te modyfikacje; zazwyczaj wymagają one najwięcej czasu na implementację.

Krok 4: przygotowanie tsconfig dla TypeScript 7

Angular 22 nadal obsługuje TypeScript 5.x i 6.x, więc TSGo nie jest jeszcze konieczne. Zmienia jednak domyślne ustawienia, które mogą zakłócić sprawdzanie typów. Najbardziej widoczną zmianą jest types: domyślnie ma on wartość pustego tablicy, więc deklaracje globalne z pakietów takich jak @types/node lub @types/jest nie są już automatycznie wykrywane. Globalne zmienne takie jak process, describe czy expect powodują wtedy błędy typu „cannot find name”.

Rozwiązaniem jest wyraźne wymienienie pakietów typów potrzebnych w każdym projekcie:

// tsconfig.json
"compilerOptions": {
  // You must now explicitly declare ambient types for TSGo compatibility
  "types": ["node", "jest"]
}

Ustaw to w tsconfig: kod aplikacji zazwyczaj wymaga mniej zmiennych globalnych niż kod testowy, a umieszczenie jest w konfiguracji aplikacji spowodowałoby wyciek zmiennych globalnych testowych do typów produkcyjnych.

Lista kontrolna migracji

• Zastąp @angular-devkit/build-angular:browser przez @angular/build:application w pliku angular.json.
• Zmień nazwę pliku main na browser, wybierz układ outputPath i połącz ustawienia SSR z jedynym celem.
• Przenieś dostosowane ładowarki Webpacka do konfiguracji zasobów lub pluginów esbuild.
• Usuń @ngtools/webpack oraz inne zależności budujące dostępne tylko dla Webpacka z pliku package.json, gdy już nic ich nie odwołuje.
• Ogłoś środowiskowe types wyraźnie w każdym tsconfig przed wersją TypeScript 7.

Sama zamiana narzędzia do budowania to niewielka zmiana konfiguracji; trudności pojawiają się przy tworzeniu dostosowanych loaderów oraz ustalaniu ścieżek deplojowania. Zrobienie tego teraz eliminuje zależność od przestarzałego procesu i umożliwia projektowi korzystanie z szybszych kompilatorów, gdy tylko pojawią się. Aby utworzyć nowy projekt przy użyciu obecnego zestawu narzędzi, zobacz tworzenie nowoczesnego projektu Angular 22.