Angular libraries with Ivy

×

Migration guide

Ivy ? 🤔

@MartinaKraus11

In a nutshell 🌰

New Renderer since version 9

Focusing on small bundle size

Together with Bazel up 30% faster compilation time

Angular Apps should be easier to debug

@MartinaKraus11

Backwards compatibility?

Angular provides two compilers:

@MartinaKraus11

• Ngtsc (Ivy compiler): compiles Ivy-compatible code

• Ngcc (Compatibility Compiler): Convert old style modules  

And Libraries?

@MartinaKraus11

That's me, Martina

GDE in Angular

Women Techmakers Ambassador

Trainer and Consultant

@MartinaKraus11

ngGirls

@MartinaKraus11

The issues of compiling Angular projects

@MartinaKraus11

Compiling Angular projects

@MartinaKraus11

• The Code that will be compiled with Ivy uses the ngtsc compiler

• Libraries, npm modules, other dependencies are already precompiled

  • incompatible to the way ngtsc compiles Angular code

• Angular team provides the compatibility compiler 

Angular Compatibility Compiler (ngcc)

@MartinaKraus11

Compatibility Compiler

@MartinaKraus11

• ngcc scans node_modules and produces Ivy-compatible versions of each package

• detects the Angular Package Format (APF) and searches for .metadata.json file and the package's entrypoint

• creates output directory ngcc_node_modules (default)

Compatibility Compiler

@MartinaKraus11

copied

copied

converted

Ok, what about the Libs now?

@MartinaKraus11

Angular Libs with Ivy

@MartinaKraus11

Using Libraries

Lib author

Using incompatible Libraries

@MartinaKraus11

Entrypoints failure

@MartinaKraus11

#1: Error: Failed to compile entry-point <packagename> due to compilation errors:
node_modules/<packagename>/bundles/filename.umd.js(1034,34)]

The issue:

ngcc wasn't able to find a proper entrypoint for converting instructions nor able to create wrapper files

Possible solution (1)

@MartinaKraus11

• Make sure your dependency is on the latest version
• Provide configuration to modify how ngcc views entry-points to packages:
  • Giving metadata information for ngcc to find the correct files
  • Provided inside a ngcc.config.js file at the root of the package

Example ngcc.config.js

@MartinaKraus11

Possible solution (2)

@MartinaKraus11

• Create a ngcc configuration for the compiler to ignore it
  • create your own wrapper classes and patch files
• Remove the package from your dependencies
• Try to avoid dependencies not following the APF
• Open a PR for the Library maintainer

Angular Libraries as an Author

@MartinaKraus11

Recommendation for lib authors

@MartinaKraus11

• You need to publish View Engine AOT-compiled Angular libs
• Additionally publish AOT-compiled libraries for version > 10

Libraries can be compiled ahead-of-time and be published as such to NPM, GitHub Packages etc.

@MartinaKraus11

Supporting both compiler

@MartinaKraus11

1. Using Git tags or branches to divide the code
2. To support differences between View Engine and Ivy we can use detection logic
   • can be used to detect ivy components, ivy directives etc.

Angular Ivy detection

@MartinaKraus11

Breaking changes:

https://angular.io/guide/ivy-compatibility

@MartinaKraus11

Prepare your library for ngcc

@MartinaKraus11

• The compatibility compiler can require some changes to your library
• Use the ngcc validation project by the Angular team
  • https://github.com/angular/ngcc-validation
• Provide your libraries in a proper Angular Package Format ...
• ... or with proper entrypoint configuration

Angular Package Format:

Do I need to add EVERYTHING manually?

@MartinaKraus11

ng-packagr

@MartinaKraus11

ng-packagr transpiles your libraries to Angular Package Format

>>npm install -D ng-packagr

ng-packagr

@MartinaKraus11

Features:

• Implements APF
• can be consumed by Angular CLI, Webpack ...
• creates type definitions
• Inlines templated and Stylesheets

https://github.com/ng-packagr/ng-packagr/blob/master/README.md

Summary

@MartinaKraus11

• Publish ViewEngine AOT-compiled bundle for version 9
• Publish an Ivy AOT-compiled bundle for Angular version 10
• Use the ngcc library 
• Resolve Ivy compatibility issues
• support differences between both compilers
• make sure you follow the Angular Package Format

me@martina-kraus.io

@MartinaKraus11

martina-kraus.io

Ping me:

Slides: slides.com/martinakraus/libs-ng-poland

Thank you !!!