Refactored the `CommonEngine` API import path to remove Node.js dependencies from the `@angular/ssr` main entry-point.
BREAKING CHANGE:
The `CommonEngine` API now needs to be imported from `@angular/ssr/node`.
**Before**
```ts
import { CommonEngine } from '@angular/ssr';
```
**After**
```ts
import { CommonEngine } from '@angular/ssr/node';
```
These server tests frequently fail due to timeouts. Despite efforts, the root cause has not yet been identified, so they are being marked as flaky to prevent blocking the pipeline while further investigation continues.
The Node.js types (`@types/node`) now contains the information for the `Response`
class and the global `fetch` function. The `Response` object is also globally
accessible in all versions of Node.js supported by the Angular CLI. This removes
the need to depend directly on the `undici` package.
The `undici` package is still used for unit-testing and remains as a development
dependency.
The `istanbul-lib-instrument` package provides the required functionality needed
to instrument code for test coverage within the context of the Angular CLI.
Since the build pipeline already contains a customized babel preset, this package
can be integrated directly into the pipeline.
This reduces the number of dependencies required for `@angular-devkit/build-angular`
including the deprecated `inflight` package.
Updates for all angular.io links to the new angular.dev domain. Additionally, adjustment to new resources where the equivalent does not exist on the new site (e.g. Tour of Heroes tutorial)
When creating a local development build of the repository via `yarn build --local`,
the package version for `@angular/build` within `@angular-devkit/build-angular`
will now correctly be replaced with the path to the locally built archive of
`@angular/build`.
The dev-server builder will now only provide an interface with typed fields
for the combined set of common elements for the Webpack and Vite development
server implementations. Any additional builder specific runtime fields will
still be present and accessible.
The `@angular/build` package has been introduced to house the esbuild/Vite-based
build system that was newly introduced as stable in v17. The existing
`@angular-devkit/build-angular` package will continue to contain the Webpack-based
build system and to ensure backwards compatibility it will also provide aliases
for the esbuild/Vite-based build system. The changes here are the first stage
of the builder transition and moves the `application` builder into the new package.
The application builder can now be accessed when this package is installed directly
via `@angular/build:application`.
No changes are required for existing projects.
The builder testing infrastructure and harness has been moved out of the
`@angular-devkit/build-angular` package and into a separate bazel only
module. This allows the testing code to be shared with other packages
within the repository. It also removes test only code from within
the package that is not specific any of the included builders.
This is a new `@angular-devkit/build-angular:web-test-runner` builder which invokes Web Test Runner to execute unit tests in a real browser.
The implementation calls `application` builder under the hood with some option overrides build the application to a temporary directory and then runs Web Test Runner on the output. This set up is still minimal, but sufficient to run and pass tests in the generated `ng new` application.
The `schema.json` file is directly copied from the `karma` builder, since this is intended to serve as a migration target for users coming from Karma. Most of the options don't actually work yet, which is logged when they are used.
The most interesting part of this change is configuring Jasmine to execute in Web Test Runner. This is done through the `testRunnerHtml` option which allows us to control the HTML page tests are executed on. We use `test_page.html` which very carefully controls the loading process. I opted to make a single `<script type="module">` which dynamic imports all the relevant pieces so the ordering can be directly controlled more easily. This is better than trying to manage multiple `<script>` tags and pass data between them. Ideally everything would be bundled into a single entry point, however this is not feasible due to the way that ordering requirements do not align with typical `import` structure. Jasmine must come before polyfills which must come before the runner which invokes user code. In an ideal world, this ordering relationship would be represented in `import` statements, but this is not practically feasible because Angular CLI doesn't own all the files (`./polyfills.js` is user-defined) and Jasmine's loading must be split into two places so Zone.js can properly patch it.
`jasmine_runner.js` serves the purpose of executing Jasmine tests and reporting their results to Web Test Runner. I tried to write `jasmine_runner.js` in TypeScript and compile it with a `ts_library`. Unfortunately I don't think this is feasible because it needs to import `@web/test-runner-core` at runtime. This dependency has some code generated at runtime in Web Test Runner, meaning we cannot bundle this dependency and must mark it as external and dynamic `import()` the package at runtime. This works fine in native ESM, but compiling with TypeScript outputs CommonJS code by default (and I don't believe our `@build_bazel_rules_nodejs` setup can easily change that), so any `import('@web/test-runner-core')` becomes `require('@web/test-runner-core')` which fails because that package is ESM-only. The `loadEsmModule` trick does work here either because Web Test Runner is applying Node module resolution at serve time, meaning it looks for `import('@web/test-runner-core')` and rewrites it to something like `import('/node_modules/@web/test-runner-core')`. In short, there is no easy syntax which circumvents the TypeScript compiler while also being statically analyzable to Web Test Runner.
The underlying file watching functionality now uses the `watchpack` library for all
builders. This includes the Webpack-based `browser` and the esbuild-based `application`/
`browser-esbuild`. This not only has the advantage of a single dependency for both but also
provides more consistent behavior between the two build system in regards to file watching.
Since the implementation of the file watching is fully encapsulated, there is no change to
the options or configurations of consuming applications.
The stylesheet url() resource plugin will now correctly issue warnings for the usage of Webpack
specific prefixes such as the tilde when used in an imported Sass file. Previously, these URLs
would be rebased by the Sass processing step which would cause the tilde prefix to no longer
be a prefix. This would then no longer be considered a warning due to the tilde no longer being
the first character of the URL value. Additionally, a warning is also now issued for the previously
unsupported but available caret prefix. Removing the caret prefix and adding the path to the
`externalDependencies` build option should provide equivalent behavior.
Previously, the application builder relied on TypeScript to detect affected component files via changes
to the internal template type check code. However, not all AOT compiler generated template errors will cause
the template type check code to be changed. Block syntax errors are one example. To ensure that component
diagnostics are recalculated when required, the component file will now always be considered affected when
a used template file is changed.
This fixes an issue were routes could not be discovered automatically in a standalone application.
This is a total overhaul of the route extraction process as instead of using `guess-parser` NPM package, we now use the Angular Router. This enables a number of exciting possibilities for the future which were not possible before.
# How it works?
The application is bootstrapped and through DI injection we get the injector and router config instance and recursively build the routes tree.
Newer versions of the babel packages allow for removing some types packages as well as some helper
packages. The `@babel/template` package export used within the CLI is accessible from the `@babel/core`
package which allows removal of `@babel/template` as a direct dependency. Also, the `@babel/plugin-proposal-async-generator-functions`
package has been transitioned to `@babel/plugin-transform-async-generator-functions` due to async generators
being merged into the ECMAScript standard. Minor code cleanup based on the type cleanup was also performed
in the build optimizer babel passes.
BREAKING CHANGE: Node.js v16 support has been removed
Node.js v16 is planned to be End-of-Life on 2023-09-11. Angular will stop supporting Node.js v16 in Angular v17.
For Node.js release schedule details, please see: https://github.com/nodejs/release#release-schedule
This commit introduces experimental support to pre-render (SSG) and app-shell generation to the new application builder.
- `appShell`: option which can have a value of `true` or `false` has been added to support generating an app-shell.
- `prerender`: option which can have a value of `true`, `false` or an object with the below listed properties can be used to static render pages;
- `routes`: Array of routes to render.
- `discoverRoutes`: Whether the builder should statically discover routes.
- `routesFile`: The path to a file containing routes separated by newlines.
The `cacache` package was only minimally used within the font inlining post-build
processing. The usage has now been replaced with direct filesystem access and key
hashing to cache any font files. This not only lowers the overall dependency count
but also provides a small performance improvement by removing the need to resolve,
load, and evaluate additional JavaScript at build time.
The file searching within the build system (both Webpack and esbuild) now use the
`fast-glob` package for globbing which provides a small performance improvement.
Since the assets option in particular is within the critical path of the buil pipeline,
the performance benefit from the switch will be most prevalent in asset heavy projects.
As an example, the Angular Material documentation site saw the asset discovery time
reduced by over half with the switch. `fast-glob` is also the package used by Vite
which provides additional benefit by ensuring that the Angular CLI behavior matches
that of the newly integrated Vite development server.
When using the esbuild-based browser application builder with the development server, an
underlying Vite server is used. The Vite server currently does not support glob-based entries
for the proxy configuration. They must either be prefix strings or regular expressions. The
Webpack-based development server, however, does support globs. To remove the need to have
different proxy configuration files for the two servers, the entries will now be normalized
to regular expressions when using the Vite server. This allows existing proxy configurations
to work without modification.
This configures polyfills to set up the environment before executing Jest tests. We need to do three things:
1. Set the global `jest` symbol. Jest executing in ESM does not provide the `jest` global and users are expected to import from `@jest/globals` or `import.meta.jest`. Zone.js is not compatible with this yet, so we need to manually define the `jest` global for Zone to read it.
2. Run user polyfills, (typically including `zone.js` and `zone.js/testing`). Zone reads the `jest` global to recognize the environment it is in and patch the relevant functions to load fake async properly. Users can override this part if they are building a Zoneless application or have custom polyfills for other browser functionality.
3. Initalize `TestBed`. This configures the `TestBed` environment so users don't have to manually configure it for each test file.
Ordering is very important for these operations, which complicates the implementation somewhat. `zone.js/testing` does not include an import on `zone.js`, meaning there was no guarnatee the bundler would sort their executions in the correct order. Similarly, `zone.js` does not import anything from Jest, so it is not trivial to inject the `globalThis.jest = import.meta.jest;` line before Zone loads. Even setting polyfills to `[jestGlobal, 'zone.js, 'zone.js/testing', initTestBed]` doesn't work because code splitting rearranges the order of operations in an incompatible way. Instead, these are implemented as distinct entry points in `browser-esbuild` with Jest's `--setupFilesAfterEnv` option executing them in the correct order.
Ideally, we could drop the global initialization altogether once Zone.js knows to look for `import.meta.jest` in an ESM context. Also we might be able to reduce down to a single polyfills entry point if `zone.js/testing` had an import on `zone.js` to apply correct ordering.
For now this just runs ESBuild-er to build test code, Jest is not actually invoked yet.
This uses `glob` to find test files matching the given pattern. I went out of my way to limit `glob` functionality as much as possible in case we change the implementation later.
Previously when using the esbuild-based browser application builder with the new dev server,
resource files referenced via stylesheets may not have been served by the development server.
The development server has now been adjusted to properly prioritize and serve files that were
generated during the build process.
Global stylesheets are also currently considered resource files as well to workaround issues
with development sourcemaps within the development server itself. Global stylesheets are already
fully processed by the build system prior to being passed to the development server.
When using the esbuild-based browser application builder and its newly supported development
server, the SSL related `dev-server` builder options can now be used. These include the existing
`ssl`, `sslCert`, and `sslKey` options. Additionally, if no certificate and key are provided
the `@vitejs/plugin-basic-ssl` plugin will be used to provide an auto-generated one.
When using the experimental esbuild-based browser application builder, the preexisting `dev-server` builder
can now be used to execute the `ng serve` command with an esbuild bundled application. The `dev-server` builder
provides an alternate development server that will execute the `browser-esbuild` builder to build the application
and then serve the output files within a development server with live reload capabilities.
This is an initial integration of the development server. It is not yet fully optimized and all features
may not yet be supported. SSL, in particular, does not yet work.
If already using the esbuild-based builder, no additional changes to the Angular configuration are required.
The `dev-server` builder will automatically detect the application builder and use the relevent development
server implementation. As the esbuild-based browser application builders is currently experimental, using
the development server in this mode is also considered experimental.
The `zone.js` package is currently built into a module structure form that resembles
UMD-like output. This causes the CommonJS checker within the experimental esbuild-based
browser application builder to issue a warning for `zone.js` usage. Until the packaging
of `zone.js` is updated to become fully ESM, the `zone.js` package is automatically allowed
when performing the CommonJS module check.
Within the build optimizer's static member optimization pass, a class that is directly
default exported must be split into two statements: the class declaration and the
default export. This is because the pass can wrap classes in a pure annotated IIFE which
results in a variable declaration replacement and variable declarations can not be directly
default exported. Previously, the pass did this splitting manually but this was causing
later babel plugins to fail. In addition to updating the AST in this case, scoping information
also needed to be updated. To support this, a babel helper package is now used that handles
the details of the statement split operation.
When using the experimental esbuild-based browser application builder, stylesheets written in the Less
stylesheet language can now be used throughout an application. The support allows Less stylesheets to
be used in all locations where CSS and/or Sass can be used. This includes global stylesheets and both
inline and external component styles. When using inline component styles, the `inlineLanguageStyle`
build option must be set to `less`.
Currently, import resolution within a Less stylesheet is limited to default Less behavior which does not
include full node package resolution. Full resolution behavior will be added in a future change.
When performing a release via the dev-infra `ng-dev` tooling, the release
builds for the packages that will be published are now performed using bazel.
Prior to this, the release builds were performed using a custom build script
that programmatically invoked TypeScript APIs. The Bazel build and discovery
process for the releasable packages is performed by a script that is based on
the scripts from components and framework repositories. Several small modifications
were performed to match the behavior and structure of the cli repository:
* Use of `packages` as the source root in the bazel query
* Use of `pkg_npm` rule in the bazel query
* Partial transition to native Node.js `fs` APIs instead of `shelljs`
* Directory creation per package when copying output (supports multiple package scopes)
* Copying of archives (tgz) for each package
The snapshot and local build capabilities are not modified as part of this change
but will be merged in a followup as part of a larger transition to use bazel
throughout the package build process.
`minimatch` was unused within the `@angular-devkit/build-angular` package.
It is still used in a repository level development script and has been kept
in the root `package.json`.
When using the experimental esbuild-based browser application builder with Sass and sourcemaps, the final
sourcemap for an input Sass stylesheet will now contain the original content for any `url` functions that
were rebased to support bundling. This required generating internal intermediate source maps for each imported
stylesheet that was modified with rebased URLs and then merging these intermediate source maps with the
final Sass generated source map. This process only occurs when stylesheet sourcemaps are enabled.
The `postcss-imports` package was previously used to support `@import` within CSS files. Unfortunately,
the package does not account for `package.json` exports fields. This prevents imports defined within that
field from working when used within a build. The `css-loader` package does provide this functionality and
is now used to provide support for CSS `@import` instead of `postcss-imports`. This change does not affect
preprocessors that provide their own import behavior.
