Пераклад аплікацыі 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.