@@ -217,15 +180,17 @@ For instance, if you clone your git repository and run `npm install`, your edito
-When you import something from a library in an Angular app, Angular looks for a mapping between the library name and a location on disk.
+When you import something from a library in an Angular application, Angular looks for a mapping between the library name and a location on disk.
When you install a library package, the mapping is in the `node_modules` folder. When you build your own library, it has to find the mapping in your `tsconfig` paths.
Generating a library with the Angular CLI automatically adds its path to the `tsconfig` file.
The Angular CLI uses the `tsconfig` paths to tell the build system where to find the library.
+For more information, see [Path mapping overview](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping).
+
-If you find that changes to your library are not reflected in your application, your app is probably using an old build of the library.
+If you find that changes to your library are not reflected in your application, your application is probably using an old build of the library.
You can rebuild your library whenever you make changes to it, but this extra step takes time.
*Incremental builds* functionality improves the library-development experience.
@@ -254,83 +219,32 @@ TypeScript path mappings should *not* point to the library source `.ts` files.
{@a ivy-libraries}
-## Building libraries with Ivy
+## Publishing libraries
-There are three distribution formats to use when publishing a library:
+There are two distribution formats to use when publishing a library:
-* View Engine _(deprecated)_—legacy format, slated for removal in Angular version 13.
- Only use this format if you must support View Engine applications.
* partial-Ivy **(recommended)**—contains portable code that can be consumed by Ivy applications built with any version of Angular from v12 onwards.
* full-Ivy—contains private Angular Ivy instructions, which are not guaranteed to work across different versions of Angular. This format requires that the library and application are built with the _exact_ same version of Angular. This format is useful for environments where all library and application code is built directly from source.
-New libraries created with Angular CLI default to partial-Ivy format.
-If you are creating a new library with `ng generate library`, Angular uses Ivy by default with no further action on your part.
-
-### Transitioning libraries to partial-Ivy format
-
-Existing libraries, which are configured to generate the View Engine format, do not change when upgrading to later versions of Angular that use Ivy.
-
-If you intend to publish your library to npm, compile with partial-Ivy code by setting `"compilationMode": "partial"` in `tsconfig.prod.json`.
-
-A library that uses View Engine, rather than Ivy, has a `tsconfig.prod.json` file that contains the following:
-
-
-
-"angularCompilerOptions": {
- "enableIvy": false
-}
-
-
-
-To convert such libraries to use the partial-Ivy format, change the `tsconfig.prod.json` file by removing the `enableIvy` option and adding the `compilationMode` option.
-
-Enable partial-Ivy compilation by replacing `"enableIvy": false` with `"compilationMode": "partial"` as follows:
-
-
-
-"angularCompilerOptions": {
- "compilationMode": "partial"
-}
-
-
-
For publishing to npm use the partial-Ivy format as it is stable between patch versions of Angular.
Avoid compiling libraries with full-Ivy code if you are publishing to npm because the generated Ivy instructions are not part of Angular's public API, and so might change between patch versions.
-Partial-Ivy code is not backward compatible with View Engine.
-If you use the library in a View Engine application, you must compile the library into the View Engine format by setting `"enableIvy": false` in the `tsconfig.json` file.
-
-Ivy applications can still consume the View Engine format because the Angular compatibility compiler, or `ngcc`, can convert it to Ivy.
-
## Ensuring library version compatibility
The Angular version used to build an application should always be the same or greater than the Angular versions used to build any of its dependent libraries.
-For example, if you had a library using Angular version 12, the application that depends on that library should use Angular version 12 or later.
+For example, if you had a library using Angular version 13, the application that depends on that library should use Angular version 13 or later.
Angular does not support using an earlier version for the application.
-
-
-The Angular CLI uses Ivy to build applications and no longer uses View Engine.
-A library or an application built with View Engine cannot consume a partial-Ivy library.
-
-
-
-Because this process happens during the application build, it uses the same version of the Angular compiler, ensuring that the application and all of its libraries use a single version of Angular.
If you intend to publish your library to npm, compile with partial-Ivy code by setting `"compilationMode": "partial"` in `tsconfig.prod.json`.
-This partial format is stable between different versions of Angular, so is safe to publish to npm.
+This partial format is stable between different versions of Angular, so is safe to publish to npm. Code with this format is processed during the application build using the same version of the Angular compiler, ensuring that the application and all of its libraries use a single version of Angular.
-Avoid compiling libraries with full-Ivy code if you are publishing to npm because the generated Ivy instructions are not part of Angular's public API, and so might change between patch versions.
-
-Partial-Ivy code is not backward compatible with View Engine.
-If you use the library in a View Engine application, you must compile the library into the View Engine format by setting `"enableIvy": false` in the `tsconfig.json` file.
-Ivy applications can still consume the View Engine format because the Angular compatibility compiler, or `ngcc`, can convert it to Ivy in the Angular CLI.
+Avoid compiling libraries with full-Ivy code if you are publishing to npm because the generated Ivy instructions are not part of Angular's public API, and so might change between patch versions.
If you've never published a package in npm before, you must create a user account. Read more in [Publishing npm Packages](https://docs.npmjs.com/getting-started/publishing-npm-packages).
-
## Consuming partial-Ivy code outside the Angular CLI
An application installs many Angular libraries from npm into its `node_modules` directory.
@@ -351,3 +265,5 @@ The Angular linker Babel plugin supports build caching, meaning that libraries o
The Angular CLI integrates the linker plugin automatically, so if consumers of your library are using the CLI, they can install Ivy-native libraries from npm without any additional configuration.
+
+@reviewed 2021-10-29