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 !!!

Made with Slides.com