What is the purpose of the esm directories in the Angular 2 modules?

Question

I am working with Angular2 RC4:

    "@angular/common": "2.0.0-rc.4",
    "@angular/compiler": "2.0.0-rc.4",
    "@angular/core": "2.0.0-rc.4",
    "@angular/forms": "0.2.0",
    "@angular/http": "2.0.0-rc.4",
    "@angular/platform-browser": "2.0.0-rc.4",
    "@angular/platform-browser-dynamic": "2.0.0-rc.4",
    "@angular/router": "3.0.0-beta.2",
    "@angular/upgrade": "2.0.0-rc.4",

and I am using JetBrains IntelliJ IDEA 2016.2. When I reference Angular2 directives the IDE helpfully offers to import the package in which the directive is defined. Unfortunately the IDE is finding multiple definitions of the directives which means that I have to choose the correct one from a list that is provided. Occasionally I will choose the "wrong" one and I'll end up with a large number of compilation errors. As I've come to learn, the wrong package is always/normally the one in an Angular2 distribution directory containing an esm subfolder.

Upon inspection of any esm folder it's contents closely mimic those of the sibling src folder (for instance):

@angular
  common
  + esm
    + src
      + directives
      + facade
      + form-deprecated
      + location
      + pipes
        common_directives.d.ts
        common_directives.js
        common_directives.js.map
        common_directives.metadata.json
        directives.d.ts
        ...
        pipes.js
        pipes.js.map
  + src
    + directives
    + facade
    + form-deprecated
    + location
    + pipes
      common_directives.d.ts
      common_directives.js
      common_directives.js.map
      common_directives.metadata.json
      directives.d.ts
      ...
      pipes.js
      pipes.js.map

Question 1: What is the purpose of the esm directories and why are these provided in the distribution?

Question 2: As an Angular2 application developer do I have need of the files in these directories?

Question 3: If "No" to question 2 can I safely remove these from my project and/or is there a way to make IntelliJ IDEA 2016.2 ignore these folders?

Answer 1

Question 1: The esm folder contains the library written in pure ES2015 (or ES6) module syntax. There are two main community created flavours of module in JavaScript-land, AMD and CommonJS, but ES2015 module is the first time a module syntax is actually part of the language. Code written in ES6 modules is future-proof: the syntax is nicer, cyclic dependencies are supported and modules export bindings rather than values. ES2015 module is more efficient than the other formats and can facilitate the creation of smaller bundle size through tree-shaking technique, i.e., importing just the bits you need instead of importing the whole thing. The community has already created tools that take advantage of the ES2015 module. As an example, the rollup.js library is a JavaScript module bundler that uses tree-shaking technique to generate smaller bundles.

So, why the Angular team has included the esm distribution? Well, although nowadays the browsers don't fully support ES2015 syntax, you can use tools like rollup.js to take full advantage of the ES2015 module syntax to produce a super lean bundle of your application.

Question 2: Like I said before, you can (or must) use the esm directory to generate a smaller bundle of your application using rollup.js library for example.

Question 3: You don't need to remove anything. esm directory is your best friend when you have to generate a bundle of your application for production.

An excellent reference for all of it is the rollup.js wiki page. Take a look.

You can also read the excellent article Building and Angular 2 Application for Production that shows how to use rollup.js and tree-shaking.

** Bonus **: Inspecting a package.json of a library you can see if it has included a ES2015 version. Just look for the jsnext:main property. For more details about it you can read the rollup - jsnext:main documentation.