Skip to content

Commit

Permalink
docs: Npm Packages guide for CLI (#19850)
Browse files Browse the repository at this point in the history
  • Loading branch information
@wardbell @vicb
wardbell authored and vicb committed Nov 2, 2017
1 parent 132c071 commit a91252a
Showing 1 changed file with 78 additions and 168 deletions.
246 changes: 78 additions & 168 deletions aio/content/guide/npm-packages.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,18 @@
# Npm Packages

Angular applications and Angular itself depend upon features and functionality provided by a variety of third-party packages.
These packages are maintained and installed with the Node Package Manager (<a href="https://docs.npmjs.com/">npm</a>).
The [**Angular CLI**](https://cli.angular.io/), Angular applications, and Angular itself depend upon features and functionality provided by libraries that are available as [**npm**](https://docs.npmjs.com/) packages.

<div class="l-sub-section">
You can download and install these npm packages with the [**npm client**](https://docs.npmjs.com/cli/install), which runs as a node.js application.

The [**yarn client**](https://yarnpkg.com/en/) is a popular alternative for downloading and installing npm packages.
The Angular CLI uses `yarn` by default to install npm packages when you create a new project.

<div class="l-sub-section">

Node.js and npm are essential to Angular development.

<a href="https://docs.npmjs.com/getting-started/installing-node" title="Installing Node.js and updating npm">
Get them now</a> if they're not already installed on your machine.
[Get them now](https://docs.npmjs.com/getting-started/installing-node "Installing Node.js and updating npm")
if they're not already installed on your machine.

**Verify that you are running node `v4.x.x` or higher and npm `3.x.x` or higher**
by running the commands `node -v` and `npm -v` in a terminal/console window.
Expand All @@ -20,244 +22,152 @@ Consider using [nvm](https://github.com/creationix/nvm) for managing multiple
versions of node and npm. You may need [nvm](https://github.com/creationix/nvm) if
you already have projects running on your machine that use other versions of node and npm.


</div>



During [Setup](guide/setup), a <a href="https://docs.npmjs.com/files/package.json">package.json</a>
file is installed with a comprehensive starter set of
packages as specified in the `dependencies` and `devDependencies` sections.

You can use other packages but the packages in _this particular set_ work well together and include
everything you need to build and run the sample applications in this series.


<div class="l-sub-section">



Note: A cookbook or guide page may require an additional library such as *jQuery*.

</div>

## _package.json_

Both `npm` and `yarn` install packages identified in a [**package.json**](https://docs.npmjs.com/files/package.json) file.

You'll install more than you need for the QuickStart guide.
No worries!
You only serve to the client those packages that the application actually requests.
The CLI `ng new` command creates a default `packages.json` file for your project.
This `packages.json` specifies _a starter set of packages_ that work well together and
jointly support many common application scenarios.

This page explains what each package does. You can make substitutions later to suit your tastes and experience.
You will add packages to `packages.json` as your application evolves.
You may even remove some.

This guide focuses on the most important packages in the starter set.

#### *dependencies* and *devDependencies*

## *dependencies* and *devDependencies*
The `package.json` includes two sets of packages,
[dependencies](guide/npm-packages#dependencies) and [devDependencies](guide/npm-packages#dev-dependencies).

The *dependencies* are essential to *running* the application.
The *devDependencies* are only necessary to *develop* the application.
You can exclude them from production installations by adding `--production` to the install command, as follows:

<code-example format="." language="bash">
npm install my-application --production

</code-example>



{@a dependencies}



## *dependencies*
## *Dependencies*
The `dependencies` section of `package.json` contains:

* ***Features***: Feature packages give the application framework and utility capabilities.
* **Angular packages**: Angular core and optional modules; their package names begin `@angular/`.

* ***Polyfills***: Polyfills plug gaps in the browser's JavaScript implementation.
* **Support packages**: 3rd party libraries that must be present for Angular apps to run.

* ***Other***: Other libraries that support the application such as `bootstrap` for HTML widgets and styling.
* **Polyfill packages**: Polyfills plug gaps in a browser's JavaScript implementation.

### Angular Packages

**@angular/animations**: Angular's animations library makes it easy to define and apply animation effects such as page and list transitions.
Read about it in the [Animations guide](guide/animations).

### Feature Packages
**@angular/common**: The commonly needed services, pipes, and directives provided by the Angular team.
The [`HttpClientModule`](guide/http) is also here, in the '@angular/common/http' subfolder.

***@angular/core***: Critical runtime parts of the framework needed by every application.
**@angular/core**: Critical runtime parts of the framework needed by every application.
Includes all metadata decorators, `Component`, `Directive`, dependency injection, and the component lifecycle hooks.

***@angular/common***: The commonly needed services, pipes, and directives provided by the Angular team.

***@angular/compiler***: Angular's *Template Compiler*.
**@angular/compiler**: Angular's *Template Compiler*.
It understands templates and can convert them to code that makes the application run and render.
Typically you don’t interact with the compiler directly; rather, you use it indirectly via `platform-browser-dynamic` or the offline template compiler.
Typically you don’t interact with the compiler directly; rather, you use it indirectly via `platform-browser-dynamic` when [JIT compiling](guide/aot-compiler) in the browser.

***@angular/platform-browser***: Everything DOM and browser related, especially
the pieces that help render into the DOM.
This package also includes the `bootstrapStatic()` method
for bootstrapping applications for production builds that pre-compile templates offline.

***@angular/platform-browser-dynamic***: Includes [Providers](api/core/Provider)
and a [bootstrap](guide/ngmodule#bootstrap) method for applications that
compile templates on the client. Don’t use offline compilation.
Use this package for bootstrapping during development and for bootstrapping plunker samples.

***@angular/http***: Angular's HTTP client.

***@angular/router***: Component router.
**@angular/forms**: support for both [template-driven](guide/forms) and [reactive forms](guide/reactive-forms).

***@angular/upgrade***: Set of utilities for upgrading AngularJS applications to Angular.
**@angular/http**: Angular's old, soon-to-be-deprecated, HTTP client.

***[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.
Other viable choices include the well-regarded [webpack](https://webpack.github.io/).
**@angular/platform-browser**: Everything DOM and browser related, especially
the pieces that help render into the DOM.
This package also includes the `bootstrapStatic()` method
for bootstrapping applications for production builds that pre-compile with [AOT](guide/aot-compiler).

Your future applications are likely to require additional packages that provide
HTML controls, themes, data access, and various utilities.
**@angular/platform-browser-dynamic**: Includes [Providers](api/core/Provider)
and methods to compile and run the app on the client
using the [JIT compiler](guide/aot-compiler).

**@angular/router**: The [router module](/guide/router) navigates among your app pages when the browser URL changes.

**@angular/upgrade**: Set of utilities for upgrading AngularJS applications to Angular.

{@a polyfills}



### Polyfill packages

Angular requires certain [polyfills](https://en.wikipedia.org/wiki/Polyfill) in the application environment.
Install these polyfills using the npm packages that Angular lists in the *peerDependencies* section of its `package.json`.

You must list these packages in the `dependencies` section of your own `package.json`.


<div class="l-sub-section">

Many browsers lack native support for some features in the latest HTML standards,
features that Angular requires.
"[Polyfills](https://en.wikipedia.org/wiki/Polyfill)" can emulate the missing features.
The [Browser Support](guide/browser-support) guide explains which browsers need polyfills and
how you can add them.

The default `package.json` installs the **[core-js](https://github.com/zloirock/core-js)** package
which polyfills missing features for several popular browser.

For background on this requirement, see [Why peerDependencies?](guide/npm-packages#why-peer-dependencies).

</div>
### Support packages



***core-js***: Patches the global context (window) with essential features of ES2015 (ES6).
You may substitute an alternative polyfill that provides the same core APIs.
When these APIs are implemented by the major browsers, this dependency will become unnecessary.

***rxjs***: A polyfill for the [Observables specification](https://github.com/zenparsing/es-observable) currently before the
**[rxjs](https://github.com/benlesh/RxJS)**: Many Angular APIs return _observables_. RxJS is an implementation of the proposed [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.
You can 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.
You can pick a preferred version of *zone.js* to use (within a compatible version range)
without waiting for Angular updates.


{@a other}



### Other helper libraries

***angular-in-memory-web-api***: An Angular-supported library that simulates a remote server's web api
without requiring an actual server or real HTTP calls.
Good for demos, samples, and early stage development (before you even have a server).

***bootstrap***: [Bootstrap](http://getbootstrap.com/) is a popular HTML and CSS framework for designing responsive web apps.
Some of the samples improve their appearance with *bootstrap*.
**[zone.js](https://github.com/angular/zone.js)**: Angular relies on zone.js to run Angular's change detection processes when native JavaScript operations raise events. Zone.js is an implementation of a [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.


{@a dev-dependencies}

## *DevDependencies*

The packages listed in the *devDependencies* section of the `package.json` help you develop the application on your local machine.

## *devDependencies*
The packages listed in the *devDependencies* section of the `package.json` help you develop the application.
You don't have to deploy them with the production application although there is no 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, 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.
You don't deploy them with the production application although there is no harm in doing so.

***@types/\* ***: TypeScript definition files.
Learn more about it in the [TypeScript Configuration](guide/typescript-configuration#typings) guide.
**[@angular/cli](https://github.com/angular/angular-cli/)**: The Angular CLI tools.


**[@angular/compiler-cli](https://github.com/angular/angular/blob/master/packages/compiler-cli/README.md)**: The Angular compiler, which is invoked by the Angular CLI's `build` and `serve` commands.

{@a why-peer-dependencies}

**[@angular/language-service](https://github.com/angular/angular-cli/)**: The Angular language service analyzes component templates and provides type and error information that TypeScript-aware editors can use to improve the developer's experience.
For example, see the [Angular language service extension for VS Code](https://marketplace.visualstudio.com/items?itemName=Angular.ng-template)

## Why *peerDependencies*?

There isn't a [*peerDependencies*](https://nodejs.org/en/blog/npm/peer-dependencies/) section in the QuickStart `package.json`.
But Angular has a *peerDependencies* section in
*its* `package.json`, which has important consequences for your application.
**@types/... **: TypeScript definition files for 3rd party libraries such as Jasmine and node.

This section explains why you load the [polyfill](guide/npm-packages#polyfills) *dependency*
packages in the QuickStart application's `package.json`,
and why you'll need those packages in your own applications.

Packages depend on other packages. For example, your application depends on the Angular package.
**[codelyzer](https://www.npmjs.com/package/codelyzer)**: A linter for Angular apps whose rules conform to the Angular [style guide](guide/styleguide).

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 with one another.
**jasmine/... **: packages to support the [Jasmine](https://jasmine.github.io/) test library.

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*.
**karma/... **: packages to support the [karma](https://www.npmjs.com/package/karma) test runner.

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*."
**[protractor](https://www.npmjs.com/package/protractor)**: an end-to-end (e2e) framework for Angular apps.
Built on top of [WebDriverJS](https://github.com/SeleniumHQ/selenium/wiki/WebDriverJs).

The Angular `package.json` specifies several *peer dependency* packages,
each pinned to a particular version of a third-party package.

### You must install Angular's *peerDependencies* yourself.
**[ts-node](https://www.npmjs.com/package/ts-node)**: TypeScript execution environment and REPL for node.

When *npm* installs packages listed in *your* `dependencies` section,
it also installs the packages listed within *their* packages `dependencies` sections.
The process is recursive.

However, as of version 3, *npm* does *not* install packages listed in *peerDependencies* sections.
**[tslint](https://www.npmjs.com/package/tslint)**: a static analysis tool that checks TypeScript code for readability, maintainability, and functionality errors.

This means that when your application installs Angular, ***npm* doesn't automatically install
the packages listed in Angular's *peerDependencies* section**.

Fortunately, *npm* issues a warning (a) When any *peer dependencies* are missing, or (b)
When the application or any of its other dependencies
installs a different version of a *peer dependency*.

These warnings guard against accidental failures due to version mismatches.
They leave you in control of package and version resolution.

It is your responsibility to list all *peer dependency* packages **among your own *devDependencies***.


<div class="l-sub-section">
**[typescript](https://www.npmjs.com/package/typescript)**:
the TypeScript language server, including the *tsc* TypeScript compiler.


## So many packages! So many files!

#### The future of *peerDependencies*
The default `package.json` installs more packages than you'll need for your project.

The Angular polyfill dependencies are hard requirements. Currently, there is no way to make them optional.
A given package may contain tens, hundreds, even thousands of files,
all of them in your local machine's `node_modules` directory.
The sheer volume of files is intimidating,

However, there is an npm feature request for "optional peerDependencies," which would allow you to model this relationship better.
When this feature request is implemented, Angular will switch from *peerDependencies* to *optionalPeerDependencies* for all polyfills.
You can remove packages that you don't need but how can you be sure that you won't need it?
As a practical matter, it's better to install a package you don't need than worry about it.
Extra packages and package files on your local development machine are harmless.

</div>
By default the Angular CLI build process bundles into a single file just the few "vendor" library files that your application actually needs.
The browser downloads this bundle, not the original package files.

See the [Deployment](guide/deployment) to learn more.

0 comments on commit a91252a

Please sign in to comment.