docs(bundles): document existing bundles and their usage

pkozlowski-opensource · pkozlowski-opensource · commit 1c779d8b9e17 · 2015-12-15T01:18:44.000Z
Closes angular#5777 Closes angular#5878
diff --git a/gulpfile.js b/gulpfile.js
@@ -1113,6 +1113,10 @@ gulp.task('!bundle.testing', ['build.js.dev'], function() {
                         {sourceMaps: true});
 });
 
+gulp.task('!bundles.js.docs', function() {
+  gulp.src('modules/angular2/docs/bundles/*').pipe(gulp.dest('dist/js/bundle'));
+});
+
 gulp.task('!bundles.js.umd', ['build.js.dev'], function() {
   var q = require('q');
   var webpack = q.denodeify(require('webpack'));
@@ -1252,7 +1256,8 @@ gulp.task('bundles.js',
             '!bundle.web_worker.js.dev.deps',
             'bundles.js.umd.min',
             '!bundle.testing',
-            '!bundle.ng.polyfills'
+            '!bundle.ng.polyfills',
+            '!bundles.js.docs'
           ],
           function(done) { runSequence('!bundle.copy', '!bundles.js.checksize', done); });
 
diff --git a/modules/angular2/docs/bundles/overview.md b/modules/angular2/docs/bundles/overview.md
@@ -0,0 +1,77 @@
+# TL;DR;
+
+* If you write ES5 use _one_ of the `UMD` bundles.
+* If you experiment with Angular2 using online prototyping tools like [plnkr](http://plnkr.co/) or similar use `System.register` bundles with SystemJS loader.
+* If you use build tools like Browserify or WebPack - bundle Angular2 as part of your build.
+* For all the above cases you must use `angular2-polyfills.js` in a `script` tag to easily include polyfills and external dependencies.
+
+# Modules, barrels and bundles
+
+Angular2 source code is authored using the ES2015 standardized module format where one module corresponds to exactly one file. Multiple modules (files) can be logically grouped into so-called "barrels".
+ A bundle is a file the contains all the code for one or more barrels.
+  
+Most bundles come in several flavors:
+* regular and minified (got `.min` in their name);
+* regular and "development" (have `.dev` in their name) - "development" bundles contain in-line source maps and don't have minified flavor (minification removes in-lined source maps). 
+  
+# Bundles, their content and usage scenarios
+  
+Angular 2 distributes several types of bundles targeted at specific usages:
+  * users writing ES5 code without any transpilation steps
+  * users experimenting with Angular 2 and TypeScript/ES2015 using online tools like plunker, jsbin or similar
+  
+Since each identified scenario has slightly different requirements and constraints there are specific bundles for each use-case.
+
+## ES5 and ngUpgrade users
+
+ES5 users and AngularJS 1.x users interested in the `ngUpgrade` path can take advantage of the bundles in the [UMD format](https://github.com/umdjs/umd).
+ Those are coarse-grained bundles that combine many barrels in one final file.  
+
+filename    | list of barrels   | dev/prod | minified? 
+------------|-------------------|----------|-------------|--------------|-------------
+`angular2.umd.js` | `RxJS`, `angular2/core`, `angular2/common`, `angular2/compiler`, `angular2/platform/browser`, `angular2/platform/common_dom`, `angular2/http`, `angular2/router`, `angular2/instrumentation`, `angular2/upgrade`| prod | no
+`angular2.umd.min.js` | `RxJS`, `angular2/core`, `angular2/common`, `angular2/compiler`, `angular2/platform/browser`, `angular2/platform/common_dom`, `angular2/http`, `angular2/router`, `angular2/instrumentation`, `angular2/upgrade` | prod | yes
+`angular2.umd.dev.js` | `RxJS`, `angular2/core`, `angular2/common`, `angular2/compiler`, `angular2/platform/browser`, `angular2/platform/common_dom`, `angular2/http`, `angular2/router`, `angular2/instrumentation`, `angular2/upgrade` | dev | no
+`angular2-testing.umd.dev.js` | `RxJS`, `angular2/core`, `angular2/common`, `angular2/compiler`, `angular2/platform/browser`, `angular2/platform/common_dom`, `angular2/http`, `angular2/router`, `angular2/instrumentation`, `angular2/upgrade`, `angular2/testing`, `angular2/http/testing`, `angular2/router/testing` | dev | no
+
+**Warning**: bundles in the `UMD` format are _not_ "additive". A single application should use only one bundle from the above list.
+
+## SystemJS loader users
+
+[SystemJS loader](https://github.com/systemjs/systemjs) with on-the-fly (in a browser) transpilations support is very useful for quick experiments using tools like plunker, jsbin or similar.
+For this scenario Angular 2 is distributed with bundles in the [System.register format](https://github.com/ModuleLoader/es6-module-loader/wiki/System.register-Explained):
+
+filename    | list of barrels   | dev/prod | minified? 
+------------|-------------------|----------|-------------|--------------|-------------
+`angular2.js` | `RxJS`, `angular2/core`, `angular2/common`, `angular2/compiler`, `angular2/platform/browser`, `angular2/platform/common_dom`, `angular2/instrumentation`| prod | no
+`angular2.min.js` | `RxJS`, `angular2/core`, `angular2/common`, `angular2/compiler`, `angular2/platform/browser`, `angular2/platform/common_dom`, `angular2/instrumentation`| prod | yes
+`angular2.dev.js` | `RxJS`, `angular2/core`, `angular2/common`, `angular2/compiler`, `angular2/platform/browser`, `angular2/platform/common_dom`, `angular2/instrumentation`| dev | no
+`http.js` | `angular2/http` | prod | no
+`http.min.js` | `angular2/http` | prod | yes
+`http.dev.js` | `angular2/http` | dev | no
+`router.js` | `angular2/router` | prod | no
+`router.min.js` | `angular2/router` | prod | yes
+`router.dev.js` | `angular2/router` | dev | no
+`upgrade.js` | `angular2/upgrade` | prod | no
+`upgrade.min.js` | `angular2/upgrade` | prod | yes
+`upgrade.dev.js` | `angular2/upgrade` | dev | no
+`testing.dev.js` | `angular2/testing`, `angular2/http/testing`, `angular2/router/testing` | dev | no
+
+**Note**: bundles in the `System.register` format are "additive" - it is quite common to include several bundles in one application.
+For example people using Angular 2 with `http` and `router` would include: `angular2.js`, `http.js` and `router.js`.
+
+## Browserify / JSPM / Rollup / WebPack users
+
+Angular 2 doesn't provide any bundles for use with packaging tools Browserify or WebPack. Those tools are sophisticated enough to build optimal bundles for production use from individual Angular 2 files distributed in the npm package.
+An example of an Angular 2 project built with WebPack can be found in the [angular2-seed](https://github.com/angular/angular2-seed) repository.      
+
+# Polyfills and external dependencies
+
+Polyfills are required for Angular 2 to function properly (the exact list depends on the browser used) and external dependencies ([zone.js](https://github.com/angular/zone.js)).
+To ease setup of Angular 2 applications there is one file - `angular2-polyfills.js` - that combines:
+* a pollyfill mandatory for all browsers: [reflect-metadata](https://www.npmjs.com/package/reflect-metadata)
+* [zone.js](https://github.com/angular/zone.js)     
+
+**Note**: `angular2-polyfills.js` contains code that should be loaded into the browser as the very first code of the web application even before the module loader. The preferred solution is to load the mentioned file in a `script` tag as early as possible. 
+
+Users of pre-ES6 browsers might need to add an ES6 shim (e.g. [es6-shim](https://github.com/paulmillr/es6-shim))
