Міграція додатку Angular від Webpack Builder до @angular/build

Протягом багатьох років проекти Angular створювалися за допомогою Webpack через @angular-devkit/build-angular. Тепер стандартом у CLI є конструктор application, заснований на esbuild та походженням із @angular/build, а конструктори Webpack поступово виходять з ужитку: згідно з примітками до випуску Angular 22, оприлюдненими на момент написання цього тексту, конструктор, заснований на Webpack, офіційно вважається застарілим. Нижче наведені кроки щодо переведення існуючого додатку на новий конструктор, зміни в файлі angular.json, що потрібно робити з користувацькими завантажувачами Webpack, а також як підготувати конфігурацію TypeScript для вбудованого компілятора Go.

Чому це переведення має значення зараз

Окрім припинення підтримки, існує ще й мотивація, пов’язана з продуктивністю. TypeScript 7.0 – це версія компілятора, перенесена на мову Go під назвою TSGo або Project Corsa – на момент написання цього тексту знаходилася на стадії кандидата до випуску та рекламувалася як у 10 разів швидша за компілятор, заснований на JavaScript. План розвитку Angular передбачає подальшу роботу над цим компілятором, а інвестиції у інструменти спрямовуються на екосистему esbuild та Vite, а не на Webpack. Проекти, що використовують Webpack, не отримають цих переваг. Вважайте ці терміни критичними та перевіряйте останні оголошення.

Новий інструмент для будування проектів також спрощує структуру цілей. У Webpack для пакетів браузера, сервера та передпроцесування потрібні були окремі інструменти; інструмент application створює їх усі з однієї цілі.

Крок 1: замінити інструмент у angular.json

Відкрийте файл angular.json, знайдіть параметр build вашого проекту та визначте інструмент для створення коду для старих браузерів:

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

Замініть назву цього інструменту на уніфікований інструмент для створення додатків, поки що залишивши об’єкт опцій без змін:

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

Останні версії CLI також пропонують автоматизовану міграцію за допомогою команди ng update, яка виконує ці зміни та інші зміни опцій; перевірте документацію Angular на точну команду для вашої версії, а потім перегляньте отриманий результат порівняння.

Крок 2: налаштування опцій компіляції

Інструмент application перевіряє свої опції більш суворо, тому кілька елементів у build.options потребують уваги.

• Перейменуйте main на browser. Тепер точка входу клієнта налаштована з використанням опції browser; main більше не приймається.
• Вирішіть, який буде формат вихідних даних. Якщо використовувати звичайний рядок, наприклад "outputPath": "dist/app", інструмент створює всередині нього підкаталоги browser та server. Скрипти розгортання, які очікують файли безпосередньо в dist/app, перестануть працювати. Щоб зберегти однорівневий вихід для клієнта, використовуйте об’єктний формат та встановіть browser як порожній рядок:

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

• Об’єднайте SSR у ту саму мету. Якщо додаток використовує серверну обробку відображення, видаліть окрему мету архітектури server та перемістіть точку входу сервера до налаштувань конструктора додатка, щоб можна було за потреби здійснювати попереднє оброблення там:

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

Потім запустіть будову для продакшну та порівняйте результат із тим, чого очікує ваш сервер або CDN.

Крок 3: заміна користувацьких завантажувачів Webpack

Проекти, які розширюють процес будови за допомогою @angular-builders/custom-webpack, постраждають найбільше: будь-який користувацький завантажувач, такий як імпорти сирого SVG або трансформатор Markdown, перестає працювати в момент, коли Webpack залишає ланцюг обробки. Існує два шляхи вирішення:

• Активи, такі як SVG: використовують вбудовану конфігурацію assets Angular або посилаються на них з CSS замість імпорту через завантажувач.

Скористання власних трансформацій: реалізуйте їх як плагін esbuild та зареєструйте через @angular-builders/custom-esbuild.

Спочатку огляньте ці налаштування; зазвичай вони вимагають найбільше часу на реалізацію.

Крок 4: підготовка tsconfig для TypeScript 7

Angular 22 продовжує підтримувати TypeScript 5.x та 6.x, тому наразі TSGo не є обов’язковим. Однак він змінює стандартні налаштування, що може порушити перевірку типів. Найбільш помітною зміною є параметр types: за замовчуванням він дорівнює порожньому масиву, тому глобальні оголошення з пакетів на кшталт @types/node чи @types/jest більше не завантажуються автоматично. Через це глобали на кшталт process, describe чи expect спричиняють помилки типу „не вдається знайти ім’я“.

Щоб вирішити цю проблему, необхідно явно вказати список пакетів з типами, потрібних кожному проекту:

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

Встановіть це в tsconfig: код додатку зазвичай потребує меншої кількості глобальних змінних, ніж код тестів, і включення jest у конфігурацію додатку призведе до проникнення глобальних змінних тестів у продакшн-версії.

Чек-лист міграції

• Замініть @angular-devkit/build-angular:browser на @angular/build:application у файлі angular.json.
• Перейменуйте main на browser, виберіть формат outputPath та об’єднайте налаштування SSR у єдину мету.
• Перенесіть власні завантажувачі Webpack у конфігурацію активів або до плагінів esbuild.
• Видаліть @ngtools/webpack та інші залежності від Webpack з файлу package.json, як тільки вони більше не будуть використовуватися.
• Явно оголосіть амбієнтні types у кожному tsconfig до версії TypeScript 7.

Сама заміна будівельника є незначною зміною конфігурації; основні зусилля потрібні для створення власних завантажувачів та визначення шляхів розгортання. Виконання цього зараз усуває залежність від застарілої системи обробки та дозволяє проекту скористатися новітніми компіляторами, як тільки вони з’являються. Щоб налаштувати новий проект із поточним набором інструментів, дивіться налаштування сучасного проекту Angular 22.