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

How to update?

ng update @angular/core @angular/cli

https://update.angular.io/

@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

Do I need to compile my lib with ViewEnigne AND Ivy? 🤔

@MartinaKraus11

That's me, Martina

GDE in Angular

Women Techmakers Ambassador

Trainer and Consultant

@MartinaKraus11

ngGirls

@MartinaKraus11

Why support Ivy ? 🤔

@MartinaKraus11

How can we benefit from Ivy?

@MartinaKraus11

• Better build times, thanks to incremental compilation

• Smaller and faster bundles

• Sets the ground for Angular Elements

• Is easy to debug

• Introduces new non-zone.js based change detection

• Uses higher-order components

@MartinaKraus11

Stephen Fluin - https://blog.angular.io/version-9-of-angular-now-available-project-ivy-has-arrived-23c97b63cfa3

How does ViewEngine work?

@MartinaKraus11

ViewEngine rendering pipeline

@MartinaKraus11

HTML Template

Data

Template

Angular Interpreter

DOM

ViewEngine rendering pipeline

@MartinaKraus11

Data template

Angular Interpreter

Ivy rendering pipeline

@MartinaKraus11

HTML Template

Template instructions

DOM

Ivy template instructions

@MartinaKraus11

Ivy template instructions

@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)

Angular Package Format

@MartinaKraus11

• Describes structure and format of the package available on npm
• Provides entrypoints for several module definitions:
  • ESM5
  • ES2015
  • Universal Module Definition
• Libraries that don't use the APF aren't processed properly with ngcc
• ngcc tries to produce a "wrapper" file 

Compatibility Compiler

@MartinaKraus11

copied

copied

converted

Example: Decorators

@MartinaKraus11

Example: Decorators

@MartinaKraus11

• The ngcc uses the TypeScript parser to parse the compiled js code 

• producing a partial class using JS AST

• extract the static property definition from the partial class

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

Demo time

@MartinaKraus11

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/angular-libs

Thank you !!!