Skip to content

Commit

Permalink
docs: add component HMR information to application build system
Browse files Browse the repository at this point in the history
Add background and usage information for the new component HMR features
available in v19.
  • Loading branch information
clydin committed Nov 6, 2024
1 parent 8919c80 commit 1b82969
Showing 1 changed file with 32 additions and 2 deletions.
34 changes: 32 additions & 2 deletions adev/src/content/tools/cli/build-system-migration.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,14 @@ In v17 and higher, the new build system provides an improved way to build Angula
- Faster build-time performance for both initial builds and incremental rebuilds.
- Newer JavaScript ecosystem tools such as [esbuild](https://esbuild.github.io/) and [Vite](https://vitejs.dev/).
- Integrated SSR and prerendering capabilities.
- Automatic global and component stylesheet hot replacement, as of v19.

This new build system is stable and fully supported for use with Angular applications.
You can migrate to the new build system with applications that use the `browser` builder.
If using a custom builder, please refer to the documentation for that builder on possible migration options.

IMPORTANT: The existing Webpack-based build system is still considered stable and fully supported.
Applications can continue to use the `browser` builder and will not be automatically migrated when updating.
Applications can continue to use the `browser` builder and projects can opt-out of migrating during an update.

## For new applications

Expand Down Expand Up @@ -180,7 +181,36 @@ You can continue to use the [command line options](/cli/serve) you have used in

JavaScript-based hot module replacement (HMR) is currently not supported.
However, global stylesheet (`styles` build option) HMR is available and enabled by default.
Angular focused HMR capabilities are currently planned and will be introduced in a future version.
Angular v19 also supports component stylesheet HMR by default for both file-based and inline styles.

The stylesheet HMR capabilities are automatically enabled and require no code or configuration changes to use.
The build system will attempt to compile and process the minimal amount of application code when it detects a stylesheet only change.
In many cases, no JavaScript/TypeScript processing will be required.
When the development server determines a component style HMR update is possible the console output will show logs similar to the following:

<docs-code language="text">
Component stylesheet(s) changed.

Application bundle generation complete. [0.014 seconds]

HMR update sent to client(s).
</docs-code>

If preferred, the HMR capabilities can be disabled by setting the `hmr` development server option to `false`.
This can also be changed on the command line via:

<docs-code language="shell">

ng serve --no-hmr

</docs-code>

In addition to fully supported component stylesheet HMR, v19 provides **experimental** support for component template HMR.
Template HMR also requires no application code changes to use but currently requires the use of the `NG_HMR_TEMPLATES=1` environment variable to enable.

IMPORTANT: Component **template** HMR is experimental and is not enabled by default.
When manually enabled, there may be cases where the browser is not fully synchronized with the application code and a restart of the development server may be required.
If you encounter an issue while using this feature, please [report the bug](https://github.com/angular/angular-cli/issues) to help the Angular team stabilize the feature.

## Unimplemented options and behavior

Expand Down

0 comments on commit 1b82969

Please sign in to comment.