Skip to content

How to bundle, import, and package separate modules #3458

@jeffbcross

Description

@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

In-Progress

Unscheduled

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.

Metadata

Metadata

Assignees

Labels

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions