How to bundle, import, and package separate modules

[jeffbcross]

TL;DR skip to the table at the bottom to see how I'm suggesting we move things around

Partial Backlog Based on Proposal and Discussion

Done

• [x] #2680 @jeffbcross refactor(http): move http into its own module as sibling of angular2
• [x] #2948 @jeffbcross fix(typings): typings template should make module name at end of file dynamic
• [x] #3540 @jeffbcross feat(typings): bundle typings should be able to declare references
• [x] #3590 @jeffbcross feat(package): add "typescript" field with typings information
• [x] #3555 feat(bundles): include all bundles in npm distributions
• [x] cancelled #3416 refactor(di): move di into its own top-level module
• [x] cancelled #3415 refactor(facade): move facade into separate top-level module
• [x] cancelled #3588 feat(dist): include "core" modules in angular2 npm dist

  In-Progress

• [ ] #3713 @jeffbcross chore: re-arrange sources to better reflect npm package and import paths
• [ ] #3714 @jeffbcross chore: change bundle rules to generate one sfx module and several minimal modules

  Unscheduled

• [ ] #3423 _export type definitions for testlib
• [ ] #3651 docs: API reference should also include global/ambient object names included in sfx bundles
• [ ] #3712 chore(zone): add zone.js to bundles and npm distribution

  Goals

• Simple, predictable, consistent package installation and consumption experience for end-users
• Have minimal, logical bundles for production use (router bundle, core bundle, http bundle, full bundle with deps, etc)
• Pave path toward eventually being able to separate modules into separate repositories with independent development lifecycles
• Maximum symmetry between Dart and JavaScript publishing (naming and structure mostly)
• Logical import and require paths for end users, without having to think about hierarchy or relationships of modules (import {Http} from 'angular/http' or require('angular/router'))

  Use Cases

• User wants to create a quick code sample on plunker
• User wants to create a production app with no build process but reasonable byte size
• User wants to create a production app with a proprietary build process that creates minified bundles
• User wants to create a production app on HTTP/2 server, using SystemJS loader, with no bundles, but minified modules that are loaded when needed.

  Characteristics of Modules

• Is likely to be used outside of an angular app, without a dependency on Angular?
• Is it a runtime requirement of angular2?
• Is useful as a runtime utility for third-party Angular libraries?
• Is it primarily a tool, not useful in an app at runtime?

Module	Used Outside	Required	Useful to Plugins	Tooling
Angular2		✓
Forms			✓
Facade		✓	✓
Router
Change Detection		✓
Zone.js	✓	✓	✓
Ts2Dart			✓	✓
Dependency Injection	✓	✓	✓
Http	✓		✓
WebSocket, Storage, etc	✓		✓
Tactical	✓
Benchpress	✓			✓
Material
Test lib			✓
NgUpgrade			✓
Universal			✓
React Native Renderer			✓
Workers			✓

Proposal

• If it is not Required and not Tooling, it becomes a subdirectory of modules/angular2/ and gets its own bundle.
• If it is not Required, it should be moved to the top-level of the angular2/modules directory, , i.e. angular2/modules/http
• All bundles will be pushed to code.angularjs.org
• All runtime modules that are currently part of the core repo should be published inside of the angular2 package on NPM and Pub (zone.js should also be added to the npm dist).

Module	NPM Package Name	Pub Package	Bundle	Bundle Global	Primary Runtime JS Import Namespace*	Target Source Home (repo / path)
Angular2/Core	angular2	angular2	core.js	ngCore	angular2/core	angular/angular/modules/angular2/core
Forms	angular2	angular2	forms.js	ngForms	angular2/forms	angular/angular/modules/angular2/forms
Facade	angular2	angular2			angular2/core	angular/angular/modules/angular2/core/facade
Router	angular2	angular2	router.js	ngRouter	angular2/router	angular/angular/modules/angular2/router
Change Detection	angular2	angular2			angular2/core	angular/angular/modules/angular2/core/change_detection
Zone.js	zone.js		zone.js	ngZone		angular/zone.js
Ts2Dart	ts2dart					angular/ts2dart
Dependency Injection	di				angular2/core	angular/angular/modules/angular2/core/di
Http	ngHttp	angular2	http.js	ngHttp	angular2/http	angular/angular/modules/angular2/http
WebSocket, Storage, etc	ng...	...	....js	ng...	angular2/...	angular/angular/modules/...
Tactical	tactical		tactical.js	ngTactical		angular/tactical
Benchpress	benchpress	benchpress				angular/angular/modules/benchpress
Material	angular-material2	angular2_material	material2.js	ngMaterial	material2	angular/angular/modules/material2
Test lib	angular2	angular2	test_lib.js	ngTestLib	angular2/test_lib	angular/angular/modules/angular2/test_lib
NgUpgrade	angular2	angular2_upgrade	upgrade.js	ngUpgrade	angular2/upgrade	angular/angular/modules/angular2/upgrade
Universal	angular2_universal		**		angular2_universal	angular/universal
React Native Renderer	angular2_react_native				angular2_react_native	angular/react-native-render
Web Workers	angular2_workers	angular2_workers	web-workers.js	ngWebWorkers	angular/web-workers	angular/angular/modules/angular2/web-workers

* Primary import namespaces when used in the context of an angular 2 app, as opposed to being used independently of Angular. For example: import {FORM_DIRECTIVES} from 'angular2/forms';. \ No bundle because only used in nodejs environment.

Bundles

These will be the bundles that are exported:

• angular2.js (includes all other bundles)
• core.js
• forms.js
• http.js
• router.js
• web-worker.js
• zone.js

And these are the extensions with which each bundle will be published to code.angularjs.org and npm. Bundles will be in the bundles folder of the npm package and will be published to code.angularjs.org as code.angularjs.org/<version-number>/<bundle-name>.

• .js
• .d.ts (typings are in separate typings folder in npm distribution)
• .js.map
• .min.js (Using uglify for now, eventually using angular/ts-minify)
• .dev.js (runs in dev mode)
• .dev.js.map
• -testing.js
• -testing.js.map
• -testing.d.ts

The angular2 bundle will also get an sfx version, which will include dependencies like Rx, reflect-metadata, traceur-runtime, and will export a global ng object.

• angular2.sfx.js
• angular2.sfx.min.js
• angular2.sfx.js.map
• angular2.sfx.min.js.map

The -testing bundles will include testing utilities and mocks for the respective module. The core-testing.js will include the bulk of the testing utilities, leaving other testing bundles to mostly just include mocks.

[marclaval]

What about https://github.com/angular/angular/tree/master/modules/angular2/src/test_lib please? Is it part of one of the module listed?

[jeffbcross]

I should include angular 1 -> 2 upgrade process as use case to consider.

[jeffbcross]

@mlaval good question. Test lib and mocks should be covered here as well.

[mhevery]

I like this. :+1:

ng-upgrade and test should be included as separate bundles (ala form)

Please update the table.

[Koslun]

If you don't have a reason not to, I would also add angular/universal, angular/react-native-renderer and the future (or available?) Nativescript renderer to that table. The two latter in particular being modules that you likely wouldn't always want or require.

Either way, sounds great for all the reasons already mentioned. :+1:

[jeffbcross]

Thanks @Koslun, worth mentioning other projects like those, and we should definitely have consistent distribution strategies.

[jeffbcross]

I updated the issue with ng-universal, react-native-renderer, test lib, and ng-upgrade. I also added a column with the runtime import namespace for clarity.

@mhevery what do you think of the test lib and ng-upgrade outputs?

Also, I'm thinking there's more complexity and confusion than benefit in publishing to the angular namespace, i.e. npm install @angular/http. It only really buys us two things: 1) A simple module name by not having to include a namespace in the module name, and 2) Some small assurance to those installing/consuming packages that it's the legit angular package. I'll try to get some more insight from other team members and users on this point.

[jeffbcross]

@vsavkin right now the proposal is to move forms out of the angular2.js bundle, but still part of the angular2 distribution. Do you want to advocate for keeping forms in the bundle? This would potentially allow us to move Rx out of the core angular2.js bundle as well, since I don't think anything else in the core bundle would depend on it.

[PatrickJS]

Personally I believe @angular/angular (or @angular/framework) should hold the angular opinions (angular way) on how everything should be glued together while @angular/core only has the classes without @angular/di and modules like @angular/router, @angular/http, (@angular/forms probably not) being separate from Di if possible (not sure how that will workout probably with @angular/bootstrap). The other approach is keeping the @angular namespace to small amount of angular glue (just the Di) while allowing allowing a public version without the angular deps (ngHttp)

there needs to be a discussion later for universal distribution but for now we can just assume @angular/server or @angular/universal will work although server bootstrap and ServerDomRenderer (pending) could be moved to core.

With universal the repo needs to be able to push to other packaging systems outside of the javascript/dart ecosystem such as scala/ruby/python. This is only to ensure the developer experience is consistent but also for another reason that will be mentioned in the repo. I see universal becoming more of a list of modules that interplay within the angular ecosystem (also server version of http/router) and ensure a baseline experience but not bound by javascript, hence universal

[PatrickJS]

~~For Use Cases (perhaps even related to Migration): In my experience, there are four stages to a web app in a repo(s) lifecycle~~

1. hackable (es5) Dev from other lang Doesn't know/starting code

2. toy/example (es5ish) plunkr tutorials

3. small/medium (es5+) small, app without any 3rd party services and could ignore bundling in the build step medium, small team with many 3rd party services and build step all the way

4. large/"enterprise" (es5+, largely depends on architecture and team) large, you have a couple teams in the project one framework and possibly more than one repo "enterprise", this is where you have many teams scoped to one feature and or page, can have many frameworks within it that fall under stage three or four. lazy loading is a must

A web app, imho, grows/matures with time and so does the abstraction level/technical debt. You can also skip stages and start off at a later one (seed repos tend to be at most stage three)

The best feature of Angular1 was completely dominating the first three levels and having a great transition (refactor into higher abstractions) stories between stage one->two->three but not so much for stage four. Angular1 also stubley ensured a certain structure that allowed you to fall into the pit of success when moving to stage three (small/medium, thx to services/di/ui-router/controller/scope abstractions). The problem was the subtle structure that Angular1 suggested falls apart during the next stage (four).

With Angular2 there's a great foundation now that more patterns/concepts are pushed into the framework the fourth stage story is great. There's no great transition stories between the early stages at the moment

With Rails you can kinda cli your way to victory with stage one-two but also keep in mind the internet has now become its documentation (copy error paste in google and see answers in stackoverflow). Rails also gets questionable in stage four

That's only been my experience and my experience may not reflect everything about webdev so I could be wrong. With that said, I do propose the Use Cases/Migration could be thought up in a similar fashion comparing other frameworks if not from my examples

update(to be more focused on original issue): small/medium apps will be fine with everything under @angular/angular while larger apps prefer more control over its dependencies. These apps may need to deconstruct the bootstrap process for techniques such as code splitting and lazy loading

[mhevery]

@jeffbcross >>> what do you think of the test lib and ng-upgrade outputs? >>YES and YES

[yjbanov]

A couple of things:

• di package already exists on pub, so we'll likely need to publish it under a different name
• web-workers should have its own bundle, and renamed to angular2_workers (pub doesn't allow hyphens in package names)

[jeffbcross]

Thanks @yjbanov I updated the table with changes to di and web workers. I also added a column to the table indicating the global object name for each bundle. (i.e. the object users will interact with when loading bundles via Githubissues.

Githubissues is a development platform for aggregating issues.