Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update npm packages to be accurate for v7 #26422

Closed
wants to merge 8 commits into from
Closed

docs: update npm packages to be accurate for v7 #26422

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
b27b01b
docs: update npm packages to be accurate for v7
jenniferfell Oct 12, 2018
a16485c
fixup! docs: update npm packages to be accurate for v7
jenniferfell Oct 13, 2018
c828fe0
fixup! docs: update npm packages to be accurate for v7
jenniferfell Oct 17, 2018
3f66ed9
fixup! docs: update npm packages to be accurate for v7
jenniferfell Oct 18, 2018
effc25a
fixup! docs: update npm packages to be accurate for v7
jenniferfell Oct 19, 2018
021dd06
fixup! docs: update npm packages to be accurate for v7
jenniferfell Oct 19, 2018
a343c71
fixup! docs: update npm packages to be accurate for v7
jenniferfell Oct 19, 2018
d9415fb
fixup! docs: update npm packages to be accurate for v7
jenniferfell Oct 19, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
196 changes: 82 additions & 114 deletions aio/content/guide/npm-packages.md
View file
Open in desktop
@@ -1,173 +1,141 @@
# Npm Packages
# Workspace npm dependencies

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.
The Angular Framework, Angular CLI, and components used by Angular applicatins are packaged as [npm packages](https://docs.npmjs.com/getting-started/what-is-npm "What is npm?") and distributed via the [npm registry](https://docs.npmjs.com/).

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.
You can download and install these npm packages by using the [npm CLI client](https://docs.npmjs.com/cli/install), which is installed with and runs as a [Node.js®](https://nodejs.org "Nodejs.org") application. By default, the Angular CLI uses the npm client.

Alternatively, you can use the [yarn client](https://yarnpkg.com/) for downloading and installing npm packages.

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

<div class="alert is-helpful">

Node.js and npm are essential to Angular development.
See [Getting Started](guide/quickstart#prerequisites) for information about the required versions and installation of Node.js and npm.

[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.
If you already have projects running on your machine that use other versions of Node.js and npm, consider using [nvm](https://github.com/creationix/nvm) to manage the multiple versions of Node.js and npm.

**Verify that you are running Node.js `v8.x` or higher and npm `5.x` or higher**
by running the commands `node -v` and `npm -v` in a terminal/console window.
Older versions produce errors.
</div>

Consider using [nvm](https://github.com/creationix/nvm) for managing multiple
versions of Node.js 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.js and npm.

</div>
## `package.json`

## _package.json_
Both `npm` and `yarn` install the packages that are identified in a [`package.json`](https://docs.npmjs.com/files/package.json) file.

Both `npm` and `yarn` install packages that are identified in a [**package.json**](https://docs.npmjs.com/files/package.json) file.
The CLI command `ng new` creates a `package.json` file when it creates the new workspace.
This `package.json` is used by all projects in the workspace, including the initial app project that is created by the CLI when it creates the workspace.

The CLI `ng new` command creates a default `package.json` file for your project.
This `package.json` specifies _a starter set of packages_ that work well together and
jointly support many common application scenarios.
Initially, this `package.json` includes _a starter set of packages_, some of which are required by Angular and others that support common application scenarios.
You add packages to `package.json` as your application evolves.
You may even remove some.

You will add packages to `package.json` as your application evolves.
You may even remove some.
The `package.json` is organized into two groups of packages:

This guide focuses on the most important packages in the starter set.
* [Dependencies](guide/npm-packages#dependencies) are essential to *running* applications.
* [DevDependencies](guide/npm-packages#dev-dependencies) are only necessary to *develop* applications.

#### *dependencies* and *devDependencies*
<div class="alert is-helpful">

The `package.json` includes two sets of packages,
[dependencies](guide/npm-packages#dependencies) and [devDependencies](guide/npm-packages#dev-dependencies).
**Library developers:** By default, the CLI command [`ng generate library`](cli/generate) creates a `package.json` for the new library. That `package.json` is used when publishing the library to npm.
For more information, see the CLI wiki page [Library Support](https://github.com/angular/angular-cli/wiki/stories-create-library).
</div>

The *dependencies* are essential to *running* the application.
The *devDependencies* are only necessary to *develop* the application.

{@a dependencies}
## Dependencies
jenniferfell marked this conversation as resolved.
Show resolved Hide resolved

## *Dependencies*
The `dependencies` section of `package.json` contains:
The packages listed in the `dependencies` section of `package.json` are essential to *running* applications.

* **Angular packages**: Angular core and optional modules; their package names begin `@angular/`.
The `dependencies` section of `package.json` contains:

* **Support packages**: 3rd party libraries that must be present for Angular apps to run.
* [**Angular packages**](#angular-packages): Angular core and optional modules; their package names begin `@angular/`.

* **Polyfill packages**: Polyfills plug gaps in a browser's JavaScript implementation.
* [**Support packages**](#support-packages): 3rd party libraries that must be present for Angular apps to run.

### Angular Packages
* [**Polyfill packages**](#polyfills): Polyfills plug gaps in a browser's JavaScript implementation.

**@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).
To add a new dependency, use the [`ng add`](cli/add) command.

**@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.
{@a angular-packages}
### Angular packages

**@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.
The following Angular packages are included as dependencies in the default `package.json` file for a new Angular workspace.
For a complete list of Angular packages, see the [API reference](http://angular.io/api?type=package).

**@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` when [JIT compiling](guide/aot-compiler) in the browser.
Package name | Description
---------------------------------------- | --------------------------------------------------
[**@angular/animations**](api/animations) | Angular's animations library makes it easy to define and apply animation effects such as page and list transitions. For more information, see the [Animations guide](guide/animations).
[**@angular/common**](api/common) | The commonly-needed services, pipes, and directives provided by the Angular team. The [`HttpClientModule`](api/common/http/HttpClientModule) is also here, in the [`@angular/common/http`](api/common/http) subfolder. For more information, see the [HttpClient guide](guide/http).
**@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` when JIT compiling in the browser. For more information, see the [Ahead-of-time Compilation guide](guide/aot-compiler).
[**@angular/core**](api/core) | Critical runtime parts of the framework that are needed by every application. Includes all metadata decorators, `Component`, `Directive`, dependency injection, and the component lifecycle hooks.
[**@angular/forms**](api/forms) | Support for both [template-driven](guide/forms) and [reactive forms](guide/reactive-forms). For information about choosing the best forms approach for your app, see [Introduction to forms](guide/forms-overview).
[**@angular/http**](api/http) | Angular's legacy HTTP client, which was deprecated in version 5.0 in favor of [@angular/common/http](api/common/http).
[**@angular/<br />platform&#8209;browser**](api/platform-browser) | Everything DOM and browser related, especially the pieces that help render into the DOM. This package also includes the `bootstrapModuleFactory()` method for bootstrapping applications for production builds that pre-compile with [AOT](guide/aot-compiler).
[**@angular/<br />platform&#8209;browser&#8209;dynamic**](api/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**](api/router) | The router module navigates among your app pages when the browser URL changes. For more information, see [Routing and Navigation](guide/router).

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

**@angular/http**: Angular's old, deprecated, HTTP client.
{@a support-packages}
### Support packages

**@angular/platform-browser**: Everything DOM and browser related, especially
the pieces that help render into the DOM.
This package also includes the `bootstrapModuleFactory()` method
for bootstrapping applications for production builds that pre-compile with [AOT](guide/aot-compiler).
The following support packages are included as dependencies in the default `package.json` file for a new Angular workspace.

**@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.
Package name | Description
---------------------------------------- | --------------------------------------------------
[**rxjs**](https://github.com/ReactiveX/rxjs) | Many Angular APIs return [_observables_](guide/glossary#observable). 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, which determines standards for the JavaScript language.
[**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.

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

{@a polyfills}

### Polyfill packages

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.
[_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
The `package.json` for a new Angular workspace installs the [core-js](https://github.com/zloirock/core-js) package,
which polyfills missing features for several popular browser.

### Support packages

**[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.


**[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.


jenniferfell marked this conversation as resolved.
Show resolved Hide resolved
{@a dev-dependencies}

## *DevDependencies*

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

You don't deploy them with the production application although there is no harm in doing so.

**[@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.


**[@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)


**@types/... **: TypeScript definition files for 3rd party libraries such as Jasmine and Node.js.


**[codelyzer](https://www.npmjs.com/package/codelyzer)**: A linter for Angular apps whose rules conform to the Angular [style guide](guide/styleguide).


**jasmine/... **: packages to support the [Jasmine](https://jasmine.github.io/) test library.


**karma/... **: packages to support the [karma](https://www.npmjs.com/package/karma) test runner.


**[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).


**[ts-node](https://www.npmjs.com/package/ts-node)**: TypeScript execution environment and REPL for Node.js.

## DevDependencies
jenniferfell marked this conversation as resolved.
Show resolved Hide resolved

**[tslint](https://www.npmjs.com/package/tslint)**: a static analysis tool that checks TypeScript code for readability, maintainability, and functionality errors.
The packages listed in the `devDependencies` section of `package.json` help you develop the application on your local machine. You don't deploy them with the production application.

To add a new `devDependency`, use either one of the following commands:

**[typescript](https://www.npmjs.com/package/typescript)**:
the TypeScript language server, including the *tsc* TypeScript compiler.
<code-example language="sh" class="code-shell">
npm install --dev &lt;package-name&gt;
</code-example>

<code-example language="sh" class="code-shell">
yarn add --dev &lt;package-name&gt;
</code-example>

## So many packages! So many files!
The following `devDependencies` are provided in the default `package.json` file for a new Angular workspace.

The default `package.json` installs more packages than you'll need for your project.

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,
Package name | Description
---------------------------------------- | -----------------------------------
[**@angular&#8209;devkit/<br />build&#8209;angular**](https://github.com/angular/angular-cli/) | The Angular build tools.
[**@angular/cli**](https://github.com/angular/angular-cli/) | The Angular CLI tools.
**@angular/<br />compiler&#8209;cli** | The Angular compiler, which is invoked by the Angular CLI's `ng build` and `ng serve` commands.
**@angular/<br />language&#8209;service** | The [Angular language service](guide/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).
**@types/... ** | TypeScript definition files for 3rd party libraries such as Jasmine and Node.js.
[**codelyzer**](https://www.npmjs.com/package/codelyzer) | A linter for Angular apps whose rules conform to the Angular [style guide](guide/styleguide).
**jasmine/... ** | Packages to support the [Jasmine](https://jasmine.github.io/) test library.
**karma/... ** | Packages to support the [karma](https://www.npmjs.com/package/karma) test runner.
[**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).
[**ts-node**](https://www.npmjs.com/package/ts-node) | TypeScript execution environment and REPL for Node.js.
[**tslint**](https://www.npmjs.com/package/tslint) | A static analysis tool that checks TypeScript code for readability, maintainability, and functionality errors.
[**typescript**](https://www.npmjs.com/package/typescript) | The TypeScript language server, including the *tsc* TypeScript compiler.

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.

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.
## Related information

See the [Deployment](guide/deployment) to learn more.
For information about how the Angular CLI handles packages see the following guides:

* [Building and serving](guide/build) describes how packages come together to create a development build.
* [Deployment](guide/deployment) describes how packages come together to create a production build.
4 changes: 2 additions & 2 deletions aio/content/navigation.json
View file
Open in desktop
Expand Up @@ -517,8 +517,8 @@
},
{
"url": "guide/npm-packages",
"title": "Packages",
"tooltip": "Explanation of npm packages installed into a project by default."
"title": "npm Dependencies",
"tooltip": "Description of npm packages required at development time and at runtime."
},
{
"url": "guide/typescript-configuration",
Expand Down