Angular Package Format (APF) v8.

0 
authors: iminar@ & jasonaden@, last update: 2019-02-20, status: implemented 
doc url: h
​ ttps://goo.gl/jB3GVv​, edit/comment url: ​https://goo.gl/NGBfjF  
previous version archive: ​v4​, ​v5​, ​v6 
 
This document describes the structure and format of the Angular framework packages 
currently available on npm. This format applies to packages distributing Angular 
components (like Angular Material) as well as the core framework packages published 
under the ​@angular​ namespace, such as @ ​ angular/core​ and ​@angular/forms​. 
 
The format described here uses a distinct file layout and metadata configuration that 
enables a package to work seamlessly under most common scenarios where Angular is 
used, and makes it compatible with the tooling offered by the Angular team and the 
community itself. For that reason, third-party library developers are also strongly 
encouraged to follow the same structure. 
 
The versioning of the format is aligned with the versioning of Angular itself and we expect 
the format to evolve in forward-compatible way to support the needs of the Angular 
component and tooling ecosystem. 
 

Useful Community Resources 

 
Juri Strumpflohner covered the Angular Package Format in depth in his ng-be 2017 talk 
Create and publish Angular libs like a Pro​. 
 
There are two community tools that helps with the process of scaffolding a library project 
and setting up the build system: 
 
● Jurgen Van de Moere created a Yeoman generator g ​ enerator-angular2-library 
● David Herges created ​ng-packagr​ which allows libraries to be built and packaged 
using a single command 
 
 

Purpose of the package format 

In today’s JavaScript landscape, developers will consume packages in many different ways. 
For example, some may use SystemJS, others could use Webpack. Still, others might 
consume packages in Node or maybe in the browser as a UMD bundle or through global 
 variable access. 
 
The Angular distribution package supports all of the commonly used development tools 
and workflow, and adds emphasis on optimizations that result either in smaller application 
payload size or faster development iteration cycle (build time). 
 

File layout 
This is an abbreviated version of the @angular/core package with explanation of the 
purpose of various files. 
 
Note: in APF v6 and before, each entry point would have a `src` directory next to the .d.ts entry 
point. This is still allowed in v8, but we now prefer to run the .d.ts bundler tool from 
https://api-extractor.com/​ so that the entire API appears in a single file. This avoids users finding 
deep-import paths offered by their editor and accidentally importing private symbols from them. 
 

node_modules​/​@angular​/​core - Package root

├──​ README​.​md - Readme file used by npmjs web UI
|
├──​ esm2015
| ​├── core - Directory containing individual internal modules.
| | ​├──​ ....js - Modules - all paths to these files are private api.
| ​├── testing - Similar to "core" but for secondary entry-points
| | ​├──​ ....js - Same as above.
│​ ​├──​ core​.​js (ESM/ES2015) - Public module that reexports all symbols under core/
│​ ​├──​ core​.​js.map - Source map
| ├──​ testing.js - Public module that reexports all symbols under testing/
│​ ​└──​ testing​.​js.map - Source map
|
├──​ esm5 - ESM+ES5 distribution. This directory should look
│​ ​├──​ core​.​js (ESM/ES5) identical to the ESM2015 directory
│​ ​├──​ core​.​js.map
| ├──​ testing.js
│​ ​└──​ testing​.​js.map
|
├──​ fesm2015 - Directory containing fesm2015 files
│​ ​├──​ core​.​js (ESM/ES2015) - ESM+ES2015 flat module (fesm)
│​ ​├──​ core​.​js.map - Source map (map files exist next to all .js files)
| ├──​ testing.js - Secondary entry point within the @angular/core
│​ ​└──​ testing​.​js.map package.
|
├──​ fesm5 - Directory containing fesm2015 files
│​ ​├──​ core​.​js (ESM/ES5) - ESM+ES2015 flat module (fesm)
│​ ​├──​ core​.​js.map - Source map (map files exist next to all .js files)
| ├──​ testing.js - Secondary entry point within the @angular/core package.
│​ ​└──​ testing​.​js.map
|
├──​ bundles - Directory that contains all bundles (UMD/ES5)
│​ ​├──​ core​.​umd​.​js - Primary bundle. Filename: $PKGNAME.umd.js
│​ ​├──​ core​.​umd.min​.​js - Primary minified bundle. $PKGNAME.umd.min.js
│​ ​├──​ core-testing​.​umd​.​js - Secondary bundles are prefixed with "$PKGNAME-"
│​ ​└──​ core​-​testing​.​umd.min​.​js - Minified secondary bundle
|
├──​ package​.​json - Primary package.json. Contains the keys listed to the
| typings: ./core.d.ts left, pointing to typings root as well as the main
| main: ./bundles/core.umd.js bundle and flat modules.
| module: ./esm5/core.js
| es2015: ./esm2015/core.js
|
├──​ core.d.ts - Primary flattened type definitions
├── core.metadata.json - Metadata used by AOT compiler
├── testing.d.ts - Secondary entry point type defs re-exported
├── testing.metadata.json - Secondary entry point metadata
└──​ testing
​├──​ testing.d.ts - Secondary flattened type definitions
​├──​ testing.metadata.json - Secondary entry point dir (testing, animations, etc)
└──​ package.json -
typings: ./testing.d.ts - Type defs
main: ../bundles/core-testing.umd.js - Metadata
module: ../esm5/testing.js - Secondary entry point package.json. Maps typings and
es2015: ../esm2015/testing.js JavaScript files similar to the primary entry
package.json

This package layout allows us to support the following usage-scenarios and environments: 
 
 
Build / Bundler /  Module  Primary Entry Point resolves  Secondary Entry Points resolves 
Consumer  Format  to  to 

WebPack  ESM+  fesm2015/core.js fesm2015/testing.js

(optimized) /  ES2015 
Closure Compiler  (flattened) 

CLI / Rollup /  ESM+ES5  fesm5/core.js fesm5/testing.js

WebPack  (flattened) 

WebPack v4  ESM+  esm2015/core.js esm2015/testing/testing.js

(optimized)  ES2015 
WebPack v4  ESM+  esm5/core.js esm5/testing/testing.js
ES5 

Plunker / Fiddle /  UMD  Requires manual resolution by Requires manual resolution by the
ES5 / script tag  the developer to: developer to:

bundles/core.umd.js and bundles/core-testing.umd.js

bundles/core.umd.min.js

Node.js  UMD  bundles/core.umd.js bundles/core-testing.umd.js

TypeScript  ESM+d.ts  core.d.ts testing/testing.d.ts

AOT compilation  .metadata. @angular/core/core.metadata.jso @angular/core/testing.metadata.json

json  n

Library File layout 

Libraries should use generally the same layout, but there are characteristics in libraries that 
are different from the Angular framework. 
 
Typically libraries are split at the component or functional level. Let’s take an example such 
as Angular’s Material project. 
 
Angular Material publishes sets of components such as B ​ utton​ (a single component), ​Tabs 
(a set of components that work together), etc. The common ground is the N ​ gModule​ that 
binds these functional areas together. There is a single N ​ gModule​ for ​Button​, another for 
Tabs​, and so on. 
 
The general rule in the Angular Package Format is to produce a FESM file for the smallest 
set of logically connected code. For example, the Angular package has a single FESM for 
@angular/core​. When a developer uses the Component symbol in ​@angular/core​, there 
are transitive dependencies such as I ​ njectable​, ​View​, ​Renderer​, etc. Therefore all these 
pieces are bundled together into a single FESM. For most libraries, this common bundling 
point would be an N ​ gModule​. 
 
Here is an example of how the Angular Material project would look in this format: 
 

node_modules​/​@angular/material - Package root

├──​ README​.​md - Readme file used by npmjs web UI
|
├──​ fesm2015 - Directory containing ESM2015 files
│​ ​├──​ index​.​js (ESM/ES2015) - This index re-exports from @angular/material/button,
│​ ​├──​ index​.​js.map tabs, etc
| ├──​ button.js - Secondary entry points are flattened into a single
| ├──​ button.js.map JavaScript file
| ├──​ tabs.js
| ├──​ tabs.js.map
| └──​ ...others
|
├──​ fesm5 - ESM+ES5 flat modules. This directory should look
│​ ​├──​ index​.​js (ESM/ES5) identical to the ESM2015 directory using ECMAScript
│​ ​├──​ index​.​js.map Modules but with an ES5 language level.
| ├──​ button.js
| ├──​ button.js.map
| └──​ ...others
|
├──​ bundles - Directory that contains all bundles (UMD/ES5)
│​ ​├──​ material​.​umd​.​js - Primary bundle. Filename: $PKGNAME.umd.js
│​ ​├──​ material​.​umd.min​.​js - Primary minified bundle. $PKGNAME.umd.min.js
│​ ​├──​ material-button​.​umd​.​js - Secondary bundles are prefixed with "$PKGNAME-"
│​ ​├──​ material-button​.​umd.min​.​js - Minified secondary bundle
│​ ​└──​ material-[component]​.​umd​.​js - Others...
│
├──​ tabs - Secondary entry point dir (button, tabs, etc)
│​ ​├──​ index.d.ts - Type def reference to src directory
│​ ​├──​ index.metadata.json - Flat Module metadata file
│​ ​└──​ package.json - Secondary entry point package.json. Maps typings and
| typings: ./index.d.ts JavaScript files similar to the primary entry
| main: ../bundles/material-tabs.umd.js package.json
| module: ../fesm5/tabs/index.js
| es2015: ../fesm2015/tabs/index.js
|
├──​ package​.​json - Primary package.json. Contains the keys listed to the
| typings: ./index.d.ts left, pointing to typings root as well as the main
| main: ./bundles/material.umd.js bundle and flat modules.
| module: ./fesm5/index.js
| es2015: ./fesm2015/index.js
|
├──​ index.d.ts - Primary d.ts entry point
└​── index.metadata.json - Metadata used by AOT compiler

README.md 
 
The readme file is used to display marked up description of a package on npm and github. 
 
Example readme content of @angular/core package: 
 
Angular
=======

The sources for this package are in the main

[Angular](https://github.com/angular/angular) repo. Please file issues and
pull requests against that repo.

License: MIT
 
 

Primary Entry-point 
 
Primary entry point of the package is the module with module id matching the name of the 
package (e.g. for "@angular/core" package, the import from the primary entry-point looks 
like: ​import {Component, ...} from '@angular/core'​). 
 
The primary entry-point is configured primarily via the package.json in the package root via 
the following properties: 
 
{
​"name"​:​ ​"@angular/core"​,
​"module"​:​ ​"./fesm5/core.js"​,
​"es2015"​:​ ​"./fesm2015/core.js"​,
​"esm5"​:​ ​"./esm5/core.js",
​"esm2015"​:​ ​"./esm2015/core.js",
​"fesm5"​:​ ​"./fesm5/core.js",
​"fesm2015"​:​ ​"./fesm2015/core.js",
​"main"​:​ ​"bundles/core.umd.js"​,
​"typings"​:​ ​"core.d.ts",
"sideEffects": false
}

 
 
Property Name  Purpose 

module  Tools consuming ESM+ES5 (CLI, WebPack, Rollup). 

This entry-point currently points these tools to fems5 (​note on 
reasoning​). 

es2015  Property is used by tools consuming ESM+ES2015 (Closure, custom 

Webpack build). 
This entry-point currently points these tools to fesm2015 (​note on 
reasoning​). 
 fesm5  Points to the entry-point for the flattened ESM+ES5 distribution. 

fesm2015  Points to the entry-point for the flattened ESM+ES2015 distribution. 

esm5  Points to the entry-point for the unflattened ESM+ES5 distribution. 

esm2015  Points to the entry-point for the unflattened ESM+ES2015 distribution. 

main  Node.js 

typings  typescript compiler (tsc) 

sideEffects  webpack v4+ specific flag to enable advanced optimizations and code 
splitting (​see note​) 
 
 
 

Secondary Entry-point 
 
Besides the primary entry point, a package can contain zero or more secondary entry 
points (e.g. ​@angular/core/testing​). These contain symbols that we don't want to group 
together with the symbols in the main entry point for two reasons: 
 
1. users typically perceive them as distinct from the main group of symbols, and if they 
were pertinent to the main group of symbols they would have already been there. 
2. the symbols in the secondary group are typically only used in a certain scenario (e.g. 
when writing and running tests). My not including these symbols in the main 
entry-point we reduce the chance of them being accidentally used incorrectly (e.g. 
using testing mocks in production code). 
 
Module ID of an import for a secondary entry point directs a module loader to a directory 
by the secondary entry point’s name. For instance, “@angular/core/testing” resolves to a 
directory by the same name, “@angular/core/testing”. This directory contains a 
package.json file that directs the loader to the correct location for what it’s looking for. This 
allows us to create multiple entry points within a single package. 
 
The contents of the package.json for the secondary entry point can be as simple as: 
 
{
​"name"​:​ ​"@angular/core/testing"​,
"module"​:​ ​"../fesm5/testing.js"​,
​"es2015"​:​ ​"../fesm2015/testing.js",
​"esm5"​:​ ​"../esm5/testing.js",
 ​"esm2015"​:​ ​"../esm2015/testing.js",
​"fesm5"​:​ ​"../fesm5/testing.js",
​"fesm2015"​:​ ​"../fesm2015/testing.js",
​"main"​:​ ​"../bundles/core-testing.umd.js"​,
​"typings"​:​ ​"./testing.d.ts",
"sideEffects": false
}

 
This is an example of @angular/core/testing/package.json that simply redirects 
@angular/core/testing imports to the appropriate bundle, flat module, or typings. 
 
 

Compilation and transpilation 

In order to produce all the required build artifacts, we strongly suggest that you use Angular
compiler (ngc) to compile your code with the following settings in ​tsconfig.json​:

ESM5:

{
​"compilerOptions"​:​ {
​...
​"declaration"​:​ ​true,
​"module"​:​ ​"es2015",
​"target"​:​ ​"es5"
​},
​"angularCompilerOptions"​:​ {
​"strictMetadataEmit"​:​ ​true,
​"skipTemplateCodegen"​:​ ​true,
​"flatModuleOutFile"​:​ ​"my-ui-lib.js",
​"flatModuleId"​:​ ​"my-ui-lib",
​"annotateForClosureCompiler"​:​ ​true
}
}

ESM2015: 
 
{
​"compilerOptions"​:​ {
​...
​"declaration"​:​ ​true,
​"module"​:​ ​"es2015",
​"target"​:​ ​"es2015"
​},
 ​"angularCompilerOptions"​:​ {
​"strictMetadataEmit"​:​ ​true,
​"skipTemplateCodegen"​:​ ​true,
​"flatModuleOutFile"​:​ ​"my-ui-lib.js",
​"flatModuleId"​:​ ​"my-ui-lib",
​"annotateForClosureCompiler"​:​ ​true
}
}
 

Optimizations 

Flattening of ES Modules 

We strongly recommend that you optimize the build artifacts before publishing your build 
artifacts to npm, by flattening the ES Modules. This significantly reduces the build time of 
Angular applications as well as download and parse time of the final application bundle. 
Please check out the excellent post "​The cost of small modules​" by Nolan Lawson. 
 
Angular compiler has support for generating index ES module files that can then be used to 
flattened module using tools like Rollup, resulting in a file format we call Flattened ES 
Module or FESM. 
 
FESM is a file format created by flattening all ES Modules accessible from an entry-point 
into a single ES Module. It’s formed by following all imports from a package and copying 
that code into a single file while preserving all public ES exports and removing all private 
imports. 
 
The shortened name “FESM” (pronounced “phesom”) can have a number after it such as 
“FESM5” or “FESM2015”. The number refers to the language level of the JavaScript inside 
the module. So a FESM5 file would be ESM+ES5 (import/export statements and ES5 source 
code). 
 
To generate a flattened ES Module index file, use the following configuration options in 
your t​ sconfig.json​ file: 
 
{
​"compilerOptions"​:​ {
​...
​"module"​:​ ​"es2015",
​"target"​:​ ​"es5", // for FESM5, or "es2015" for FESM15
​...
​},
 ​"angularCompilerOptions"​:​ {
​...
​"flatModuleOutFile"​:​ ​"my-ui-lib.js",
​"flatModuleId"​:​ ​"my-ui-lib"
}
} 
 
Once the index file (e.g. my-ui-lib.js) is generated by ngc, bundlers and optimizers like 
Rollup can be used to to produce the flattened ESM file. 
 
 

Note about the defaults in package.json

As of webpack v4 the flattening of ES modules optimization should not be necessary for 
webpack users, and in fact theoretically we should be able to get better code-splitting 
without flattening of modules in webpack, but in practice we still see size regressions when 
using unflattened modules as input for webpack v4. This is why "module" and "es2015" 
package.json entries still point to fesm files. We are investigating this issue and expect that 
we'll switch the "module" and "es2015" package.json entry-points to unflattened files when 
the size regression issue is resolved. 

Inlining of templates and stylesheets 

Component libraries are typically implemented using stylesheets and html templates 
stored in separate files. While it's not required, we suggest that component authors inline 
the templates and stylesheets into their FESM files as well as * ​ .metadata.json​ files by 
replacing the s​ tyleUrls​ and ​templateUrl​ with ​styles​ and ​template​ ​metadata properties 
respectively. This simplifies consumption of the components by application developers. 
 
 
webpack v4 "sideEffects": false 

As of webpack v4, packages that contain a special property called "​sideEffects​" set to 
false in their package.json, will be processed by webpack more aggressively than those that 
don't. The end result of these optimizations should be smaller bundle size and better code 
distribution in bundle chunks after code-splitting. This optimization can break your code if 
it contains non-local side-effects - this is however not common in Angular applications and 
it's a usually a sign of bad design. Our recommendation is for all packages to claim the 
side-effect free status by setting the s​ ideEffects​ property to ​false​, and that developers 
follow the ​Angular Style Guide​ which naturally results in code without non-local 
side-effects. 
More info: w ​ ebpack docs on side-effects 
  
ES2015 Language Level (experimental) 

While the most commonly used build tools today (e.g. WebPack and Uglify) expect the input 
coming from n ​ ode_modules/​ to be transpiled down to ES5. Now that all evergreen 
browsers natively support ES2015 (ES6), we encourage that the whole front-end ecosystem 
transitions over to distributing JS code at the ES2015 language level. Doing so will simplify 
the build process and will enable new optimizations resulting in better optimizations during 
packaging and minification. For this reason we encourage component authors to publish 
their libraries in a way where both ES5 and ES2015 language levels are supported. 
 
The "​es2015"​ property in package.json can be used to point tools with ES2015 support to 
the right file in your package. 

Closure compiler annotations (experimental) 

 
The ​Closure compiler​ is the most advanced JavaScript minifier available today, but in order 
for it to do a good job, it requires type hints in the form of jsdoc type annotations. These 
can be automatically generated using the ngc compiler, if the ​annotateForClosure​ flag is 
turned on in tsconfig.json: 
 
{
​"compilerOptions"​:​ {
​...
​"module"​:​ ​"es2015",
​...
​},
​"angularCompilerOptions"​:​ {
​...
​"annotateForClosureCompiler"​:​ ​true,
​...
}
} 
 
 

Examples 
● @angular/core package
● @angular/material package
● jasonaden/simple-ui-lib
● filipesilva/angular-quickstart-lib
Definition of Terms 

The following terms are used throughout this document very intentionally. In this section 
we define all of them to provide additional clarity. 
 
Package​ - the smallest set of files that are published to NPM and installed together, for 
example @angular/core. This package includes a manifest called package.json, compiled 
source code, typescript definition files, source maps, metadata, etc. The package is installed 
with ​npm install @angular/core​. 
Symbol - ​a class, function, constant or variable contained in a module and optionally made 
visible to the external world via a module export. 
Module​ - Short for ECMAScript Modules. A file containing statements that import and 
export symbols. This is identical to the definition of ​modules in the ECMAScript spec​. 
ESM -​ short for ECMAScript Modules (see above). 
FESM -​ short for Flattened ES Modules and consists of a file format created by flattening all 
ES Modules accessible from an entry-point into a single ES Module. 
Module ID​ - the identifier of a module used in the import statements, e.g. "@angular/core". 
The ID often maps directly to a path on the filesystem, but this is not always the case due to 
various module resolution strategies. 
Module Resolution Strategy -​ algorithm used to convert Module IDs to paths on the 
filesystem. Node.js has one that is ​well specified a ​ nd widely used, TypeScript supports 
several module resolution strategies​, Closure has​ yet another strategy​. 
Module Format -​ specification of the module syntax that covers at minimum the syntax for 
the importing and exporting from a file. Common module formats are CommonJS (CJS, 
typically used for Node.js applications) or ECMAScript Modules (ESM). The module format 
indicates only the packaging of the individual modules, but not the JavaScript language 
features used to make up the module content. Because of this, the Angular team often 
uses the language level specifier as a suffix to the module format, e.g. ESM+ES5 specifies 
that the module is in ESM format and contains code down-leveled to ES5. Other commonly 
used combos: ESM+ES2015, CJS+ES5, and CJS+ES2015. 
Bundle - ​an artifact in the form of a single JS file, produced by a build tool, e.g. WebPack or 
Rollup, that contains symbols originating in one or more modules. Bundles are a 
browser-specific workaround that reduce network strain that would be caused if browsers 
were to start downloading hundreds if not tens of thousands of files. Node.js typically 
doesn't use bundles. Common bundle formats are ​UMD​ and ​System.register​. 
Language Level - T ​ he language of the code (ES5 or ES2015). Independent of the module 
format. 
Entry Point -​ a module intended to be imported by the user. It is referenced by a unique 
module ID and exports the public API referenced by that module ID. An example is 
@angular/core or @angular/core/testing. Both entry points exist in the @angular/core 
package, but they export different symbols. A package can have many entry points. 
Deep Import - p ​ rocess of retrieving symbols from modules that are not Entry Points. These 
module IDs are usually considered to be private APIs that can change over the lifetime of 
the project or while the bundle for the given package is being created. 
Top-Level Import - ​an import coming from an entry point. The available top-level imports 
are what define the public API and are exposed in “@angular/name” modules, such as 
@angular/core or @angular/common. 
Tree-shaking -​ process of identifying and removing code not used by an application - also 
known as dead code elimination. This is a global optimization performed at the application 
level using tools like Rollup, Closure Compiler, or Uglify. 
AOT Compiler -​ the A ​ head of Time Compiler​ for Angular. 
Flattened Type Definitions -​ the bundled TypeScript definitions generated from 
api-extractor​.