diff --git a/public/docs/dart/latest/guide/npm-packages.jade b/public/docs/dart/latest/guide/npm-packages.jade new file mode 100644 index 0000000000..bef6020244 --- /dev/null +++ b/public/docs/dart/latest/guide/npm-packages.jade @@ -0,0 +1,8 @@ +:marked + ## NPM and NPM packages + + TypeScript and JavaScript developers rely on the Node Package Manager (*npm*) to install + angular and other libraries. + + Dart applications do not use *npm* to load 3rd party modules so + the chapter describing that process is irrelevant to Dart developers. \ No newline at end of file diff --git a/public/docs/js/latest/guide/_data.json b/public/docs/js/latest/guide/_data.json index 0b8baf2d68..4557e0cfe7 100644 --- a/public/docs/js/latest/guide/_data.json +++ b/public/docs/js/latest/guide/_data.json @@ -73,6 +73,11 @@ "intro": "Angular's hierarchical dependency injection system supports nested injectors in parallel with the component tree." }, + "npm-packages": { + "title": "npm packages", + "intro": "Details of the recommended npm packages and the different kinds of package dependencies" + }, + "upgrade": { "title": "Upgrading from 1.x", "intro": "Angular 1 applications can be incrementally upgraded to Angular 2." diff --git a/public/docs/js/latest/guide/npm-packages.jade b/public/docs/js/latest/guide/npm-packages.jade new file mode 100644 index 0000000000..6778b6af28 --- /dev/null +++ b/public/docs/js/latest/guide/npm-packages.jade @@ -0,0 +1 @@ +!= partial("../../../_includes/_ts-temp") diff --git a/public/docs/ts/latest/guide/_data.json b/public/docs/ts/latest/guide/_data.json index 8eb6c3eabc..580fbed748 100644 --- a/public/docs/ts/latest/guide/_data.json +++ b/public/docs/ts/latest/guide/_data.json @@ -73,6 +73,11 @@ "intro": "Angular's hierarchical dependency injection system supports nested injectors in parallel with the component tree." }, + "npm-packages": { + "title": "npm packages", + "intro": "Details of the recommended npm packages and the different kinds of package dependencies" + }, + "upgrade": { "title": "Upgrading from 1.x", "intro": "Angular 1 applications can be incrementally upgraded to Angular 2." diff --git a/public/docs/ts/latest/guide/npm-packages.jade b/public/docs/ts/latest/guide/npm-packages.jade new file mode 100644 index 0000000000..942f9eee10 --- /dev/null +++ b/public/docs/ts/latest/guide/npm-packages.jade @@ -0,0 +1,189 @@ +include ../../../../_includes/_util-fns + +:marked + Angular applications and Angular itself depend upon features and functionality provided by a variety of third-party packages + maintained and installed with the Node Package Manager (npm). +.l-sub-section + :marked + Don't have npm? + Get it now + because we're going to use it now and repeatedly throughout this documentation. +:marked + The Angular team recommends the starter-set of packages specified in the `dependencies` and `devDependencies` + sections of the QuickStart + package.json file: ++makeJson('quickstart/ts/package.1.json',{ paths: 'dependencies, devDependencies'}, 'package.json (dependencies)')(format=".") +:marked + There are other possible package choices. + We're recommending this particular set that we know work well together. + + In this chapter we explain what each package does and why we include it. + Feel free to make substitutions later to suit your tastes and experience. + +.l-main-section +:marked + ## *dependencies* and *devDependencies* + The `package.json` distinguishes between two sets of packages, + [dependencies](#dependencies) and [devDependencies](#dev-dependencies). + + The packages listed under *dependencies* are essential to *running* the application. + The *devDependencies* are only necessary to *develop* the application. + They can be excluded from production installations as in this example: +code-example(format="." language="bash"). + npm install my-application --production + +a(id="dependencies") +.l-main-section +:marked + ## *dependencies* + There are two package categories in the `dependencies` section of the application `package.json`: + + * ***Features*** - Feature packages provide our application with framework and utility capabilites. + + * ***Polyfills*** - Polyfills plug gaps in the browser's JavaScript implementation. + +.l-main-section +:marked + ### Feature Packages + + ***angular2*** - The framework we know and love; the reason we're all here. + + ***[system.js](https://github.com/systemjs/systemjs)*** - A dynamic module loader compatible with the + [ES2015 module](http://www.2ality.com/2014/09/es6-modules-final.html) specification. + There are other viable choices including the well-regarded [webpack](https://webpack.github.io/). + SystemJS happens to be the one we use in the documentation samples. It works. + + Our applications are likely to require additional packages that provide + HTML controls, themes, data access, and various utilities. + + +a(id="polyfills") +.l-main-section +:marked + ### Polyfill Packages + + Angular requires certain [polyfills](https://en.wikipedia.org/wiki/Polyfill) in the application environment. + We install these polyfills with very specific npm packages that Angular lists in the *peerDependencies* section of its `package.json`. + + We must list these packages in the `dependencies` section of our own `package.json`. + +.l-sub-section + :marked + See "[Why peerDependencies?](#why-peer-dependencies)" below for background on this requirement. +:marked + ***es6-promise*** - Angular applications require ES2015 promise support. + Although some browsers provide a native implementation of ES2015 promises many do not. + We still need this library even for the browsers that do support promises + in order to integrate with the current version of *zone.js* (see below). + This integration dependency goes away in the next version of *zone.js* + The need for *es6-promise* should disappear entirely once promises are implemented by all supported ever-green browsers. + + ***es6-shim*** - monkey patches the global context (window) with essential features of ES2016 (ES6). + Developers may substitute an alternative polyfill that provides the same core APIs. + This dependency should go away once these APIs are implemented by all supported ever-green browsers. + + ***reflect-metadata*** - a dependency shared between Angular and the ***TypeScript compiler***. + Developers should be able to update a TypeScript package without upgrading Angular, + which is why this is a dependency of the application and not a dependency of Angular. + + ***rxjs*** - a polyfill for the [Observables specification](https://github.com/zenparsing/es-observable) currently before the + [TC39](http://www.ecma-international.org/memento/TC39.htm) committee that determines standards for the JavaScript language. + Developers should be able to pick a preferred version of *rxjs* (within a compatible version range) + without waiting for Angular updates. + + ***zone.js*** - a polyfill for the [Zone specification](https://gist.github.com/mhevery/63fdcdf7c65886051d55) currently before the + [TC39](http://www.ecma-international.org/memento/TC39.htm) committee that determines standards for the JavaScript language. + Developers should be able to pick a preferred version of *zone.js* to use (within a compatible version range) + without waiting for Angular updates. + +a(id="dev-dependencies") +.l-main-section +:marked + ## *devDependencies* + The packages listed in the *devDependencies* section of the `package.json` help us develop the application. + They do not have to be deployed with the production application although there is rarely harm in doing so. + + ***[concurrently](https://www.npmjs.com/package/concurrently)*** - + a utility to run multiple *npm* commands concurrently on OS/X, Windows, and Linux operating systems. + + ***[lite-server](https://www.npmjs.com/package/lite-server)*** - + a light-weight, static file server, written and maintained by [John Papa](http://johnpapa.net/) + with excellent support for Angular apps that use routing. + + ***[typescript](https://www.npmjs.com/package/typescript)*** - + the TypeScript language server including the *tsc* TypeScript compiler. + + ***[typings](https://www.npmjs.com/package/typings)*** - a manager for TypeScript definition files. + Learn more about it in the [TypeScript Configuration](typescript-configuration.html#typings) chapter. + + This section likely grows as we add more tools, testing, and build support. + The QuickStart set is sufficient for developing the documentation sample applications. + +.l-main-section +a(id="why-peer-dependencies") +:marked + ## Why *peerDependencies*? + + We don't have a *peerDependencies* section in the QuickStart `package.json`. + But Angular itself has a *peerDependencies* section in + [*its* package.json](https://github.com/angular/angular/blob/master/modules/angular2/package.json) + and that has important consequences for our application. + + It explains why we load the [polyfill](#polyfills) *dependency* packages in the QuickStart `package.json`, + and why we'll need those packages in our own applications. + + Let's briefly explain what [peer dependencies](https://nodejs.org/en/blog/npm/peer-dependencies/) are about. + + As we know, packages depend on other packages. For example, our application depends upon the Angular package. + + Two packages, 'A' and 'B', could depend on the same third package 'C'. + 'A' and 'B' might both list 'C' among their *dependencies*. + + What if 'A' and 'B' depend on different versions of 'C' ('C1' and 'C2'). The npm package system supports that! + It installs 'C1' in the `node_modules` folder for 'A' and 'C2' in the `node_modules` folder for 'B'. + Now 'A' and 'B' have their own copies of 'C' and they run without interferring. This is great. + + But there is a problem. Package 'A' may require the presence of 'C1' without actually calling upon it directly. + 'A' may only work if *everyone is using 'C1'*. It falls down if any part of the application relies on 'C2'. + + The solution is for 'A' to declare that 'C1' is a *peer dependency*. + + The difference between a `dependency` and a `peerDependency` is roughly this: + + >A **dependency** says, "I need this thing directly available to *me*." + > + >A **peerDependency** says, "if you want to use me, you need this thing available to *you*." + + Angular finds itself in this situation. + Accordingly, the Angular `package.json` specifies several *peer dependency* packages, + each pinned to a particular version of a third-party package. + + ### We must install Angular's *peerDependencies* ourselves + + When *npm* installs packages listed in *our* `dependencies` section, + it also installs the packages listed within *their* packages `dependencies` sections. + The process is recursive. + + But as of version 3, *npm* does *not* install packages listed in *peerDependencies* sections. + + That means when our application installs Angular, ***npm* will not automatically install + the packages listed in Angular's *peerDependencies* section**. + + Fortunately, *npm* warns us (a) when any *peer dependencies* are missing or (b) + when the application or any its other dependencies + installs a different version of a *peer dependency*. + + These warnings are a critical guard against accidental failures due to version mismatches. + They leave us in control of package and version resolution. + + It is our responsibility to list all *peer dependency* packages **among our own *devDependencies***. + +.l-sub-section + :marked + #### The future of *peerDependencies* + + The Angular polyfill dependencies should be just a suggestion or a hint to developers so that they know what Angular expects. + They should not be hard requirements as they are today. We don't have a way to make them optional today. + + There is a npm feature request for "optional peerDependencies" which would allow us to model this relationship better. + Once implemented, Angular will switch from *peerDependencies* to *optionalPeerDependencies* for all polyfills. diff --git a/public/docs/ts/latest/quickstart.jade b/public/docs/ts/latest/quickstart.jade index 1df1ea4dbd..210fd4202f 100644 --- a/public/docs/ts/latest/quickstart.jade +++ b/public/docs/ts/latest/quickstart.jade @@ -44,19 +44,25 @@ a(id="devenv") :marked ## Development Environment - We need to set up our development environment with - * an [application project folder](#app-folder) - * a [tsconfig.json](#tsconfig) to guide the TypeScript compiler - * a [typings.json](#typings) to install TypeScript definition files - * a [package.json](#package-json) to install *npm* packages with scripts and other assets our app will need. - + We need to set up our development environment: + * install node and npm + * create an [application project folder](#app-folder) + * add a [tsconfig.json](#tsconfig) to guide the TypeScript compiler + * add a [typings.json](#typings) that identifies missing TypeScript definition files + * add a [package.json](#package-json) that defines the packages and scripts we need + * install the npm packages and typings files + +a(id="install-npm") +:marked + **Install [node and npm](https://nodejs.org/en/download/)** if not already on your machine. + a(id="app-folder") :marked Create a **new project folder** code-example(format=""). mkdir angular2-quickstart cd angular2-quickstart - + a(id="tsconfig") :marked Add a **tsconfig.json** file to the project folder and copy/paste the following: @@ -86,52 +92,18 @@ a(id="package-json") :marked Add a **package.json** file to the project folder and copy/paste the following: +makeJson('quickstart/ts/package.1.json', null, 'package.json')(format=".") - -:marked - **Install these packages** by entering the following *npm* command in a terminal window (command window in Windows): -code-example(format=""). - npm install -.alert.is-important - :marked - Scary error messages in red may appear **during** install. - The install typically recovers from these errors and finishes successfully. - .l-verbose-section(class="l-verbose-inherit") - :marked - #### npm errors and warnings - - All is well if there are no console messages starting with `npm ERR!` *at the end* of **npm install**. - There might be a few `npm WARN` messages along the way — and that is perfectly fine. - - We often see an `npm WARN` message after a series of `gyp ERR!` messages. - Ignore them. A package may try to re-compile itself using `node-gyp`. - If the re-compile fails, the package recovers (typically with a pre-built version) - and everything works. - - Just make sure there are no `npm ERR!` messages at the end of `npm install`. .l-verbose-section :marked ### Adding the libraries we need with *npm* Angular application developers rely on the npm - package manager to acquire the libraries their apps require. - - Don't have npm? - Get it now - because we're going to use it now and repeatedly throughout this documentation. - + package manager to install the libraries their apps require. The Angular team recommends the starter-set of packages specified in the `dependencies` and `devDependencies` - sections of this QuickStart - package.json file. - - +makeJson('quickstart/ts/package.1.json',{ paths: 'dependencies, devDependencies'}, 'package.json (dependencies)')(format=".") - :marked - There are other possible package choices. - We're recommending this particular set that we know work well together. - Feel free to make substitutions later to suit your tastes and experience. - - A `package.json` has an optional **scripts** section where we can define helpful - commands for development and build tasks. - We've included a number of such scripts in our suggested `package.json`: + sections. + See the [npm packages](guide/npm-packages.html) chapter for details. + + ### Helpful scripts + We've included a number of npm scripts in our suggested `package.json` to handle common development tasks: +makeJson('quickstart/ts/package.1.json',{ paths: 'scripts'}, 'package.json (scripts)')(format=".") :marked @@ -157,6 +129,29 @@ code-example(format=""). * `npm postinstall` - called by *npm* automatically *after* it successfully completes package installation. This script installs the [TypeScript definition files](#typings) this app requires. +:marked + **Install these packages** by entering the following *npm* command in a terminal window (command window in Windows): +code-example(format=""). + npm install + +.alert.is-important + :marked + Scary error messages in red may appear **during** install. + The install typically recovers from these errors and finishes successfully. + .l-verbose-section(class="l-verbose-inherit") + :marked + #### npm errors and warnings + + All is well if there are no console messages starting with `npm ERR!` *at the end* of **npm install**. + There might be a few `npm WARN` messages along the way — and that is perfectly fine. + + We often see an `npm WARN` message after a series of `gyp ERR!` messages. + Ignore them. A package may try to re-compile itself using `node-gyp`. + If the re-compile fails, the package recovers (typically with a pre-built version) + and everything works. + + Just make sure there are no `npm ERR!` messages at the end of `npm install`. + :marked **We're all set.** Let's write some code.