Миграция приложения 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.