docs: update npm packages to be accurate for v7 (#26422)
PR Close #26422
This commit is contained in:
parent
84af7b065d
commit
26e8032bd0
|
@ -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.
|
|
||||||
The Angular CLI uses `yarn` by default to install npm packages when you create a new project.
|
|
||||||
|
|
||||||
<div class="alert is-helpful">
|
<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 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.
|
||||||
if they're not already installed on your machine.
|
|
||||||
|
|
||||||
**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.
|
|
||||||
|
|
||||||
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>
|
</div>
|
||||||
|
|
||||||
## _package.json_
|
|
||||||
|
|
||||||
Both `npm` and `yarn` install packages that are identified in a [**package.json**](https://docs.npmjs.com/files/package.json) file.
|
## `package.json`
|
||||||
|
|
||||||
The CLI `ng new` command creates a default `package.json` file for your project.
|
Both `npm` and `yarn` install the packages that are identified in a [`package.json`](https://docs.npmjs.com/files/package.json) file.
|
||||||
This `package.json` specifies _a starter set of packages_ that work well together and
|
|
||||||
jointly support many common application scenarios.
|
|
||||||
|
|
||||||
You will add packages to `package.json` as your application evolves.
|
The CLI command `ng new` creates a `package.json` file when it creates the new workspace.
|
||||||
You may even remove some.
|
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.
|
||||||
|
|
||||||
This guide focuses on the most important packages in the starter set.
|
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.
|
||||||
|
|
||||||
#### *dependencies* and *devDependencies*
|
The `package.json` is organized into two groups of packages:
|
||||||
|
|
||||||
The `package.json` includes two sets of packages,
|
* [Dependencies](guide/npm-packages#dependencies) are essential to *running* applications.
|
||||||
[dependencies](guide/npm-packages#dependencies) and [devDependencies](guide/npm-packages#dev-dependencies).
|
* [DevDependencies](guide/npm-packages#dev-dependencies) are only necessary to *develop* applications.
|
||||||
|
|
||||||
|
<div class="alert is-helpful">
|
||||||
|
|
||||||
|
**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}
|
{@a dependencies}
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
The packages listed in the `dependencies` section of `package.json` are essential to *running* applications.
|
||||||
|
|
||||||
## *Dependencies*
|
|
||||||
The `dependencies` section of `package.json` contains:
|
The `dependencies` section of `package.json` contains:
|
||||||
|
|
||||||
* **Angular packages**: Angular core and optional modules; their package names begin `@angular/`.
|
* [**Angular packages**](#angular-packages): Angular core and optional modules; their package names begin `@angular/`.
|
||||||
|
|
||||||
* **Support packages**: 3rd party libraries that must be present for Angular apps to run.
|
* [**Support packages**](#support-packages): 3rd party libraries that must be present for Angular apps to run.
|
||||||
|
|
||||||
* **Polyfill packages**: Polyfills plug gaps in a browser's JavaScript implementation.
|
* [**Polyfill packages**](#polyfills): Polyfills plug gaps in a browser's JavaScript implementation.
|
||||||
|
|
||||||
### Angular Packages
|
To add a new dependency, use the [`ng add`](cli/add) command.
|
||||||
|
|
||||||
**@angular/animations**: Angular's animations library makes it easy to define and apply animation effects such as page and list transitions.
|
{@a angular-packages}
|
||||||
Read about it in the [Animations guide](guide/animations).
|
### Angular packages
|
||||||
|
|
||||||
**@angular/common**: The commonly needed services, pipes, and directives provided by the Angular team.
|
The following Angular packages are included as dependencies in the default `package.json` file for a new Angular workspace.
|
||||||
The [`HttpClientModule`](guide/http) is also here, in the '@angular/common/http' subfolder.
|
For a complete list of Angular packages, see the [API reference](http://angular.io/api?type=package).
|
||||||
|
|
||||||
**@angular/core**: Critical runtime parts of the framework needed by every application.
|
Package name | Description
|
||||||
Includes all metadata decorators, `Component`, `Directive`, dependency injection, and the component lifecycle hooks.
|
---------------------------------------- | --------------------------------------------------
|
||||||
|
[**@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‑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‑browser‑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/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.
|
|
||||||
|
|
||||||
**@angular/forms**: support for both [template-driven](guide/forms) and [reactive forms](guide/reactive-forms).
|
{@a support-packages}
|
||||||
|
### Support packages
|
||||||
|
|
||||||
**@angular/http**: Angular's old, deprecated, HTTP client.
|
The following support packages are included as dependencies in the default `package.json` file for a new Angular workspace.
|
||||||
|
|
||||||
**@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).
|
|
||||||
|
|
||||||
**@angular/platform-browser-dynamic**: Includes [Providers](api/core/Provider)
|
Package name | Description
|
||||||
and methods to compile and run the app on the client
|
---------------------------------------- | --------------------------------------------------
|
||||||
using the [JIT compiler](guide/aot-compiler).
|
[**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/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}
|
{@a polyfills}
|
||||||
|
|
||||||
### Polyfill packages
|
### Polyfill packages
|
||||||
|
|
||||||
Many browsers lack native support for some features in the latest HTML standards,
|
Many browsers lack native support for some features in the latest HTML standards,
|
||||||
features that Angular requires.
|
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
|
The [Browser Support](guide/browser-support) guide explains which browsers need polyfills and
|
||||||
how you can add them.
|
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.
|
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.
|
|
||||||
|
|
||||||
|
|
||||||
{@a dev-dependencies}
|
{@a dev-dependencies}
|
||||||
|
|
||||||
## *DevDependencies*
|
## DevDependencies
|
||||||
|
|
||||||
The packages listed in the *devDependencies* section of the `package.json` help you develop the application on your local machine.
|
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.
|
||||||
|
|
||||||
You don't deploy them with the production application although there is no harm in doing so.
|
To add a new `devDependency`, use either one of the following commands:
|
||||||
|
|
||||||
**[@angular/cli](https://github.com/angular/angular-cli/)**: The Angular CLI tools.
|
<code-example language="sh" class="code-shell">
|
||||||
|
npm install --dev <package-name>
|
||||||
|
</code-example>
|
||||||
|
|
||||||
|
<code-example language="sh" class="code-shell">
|
||||||
|
yarn add --dev <package-name>
|
||||||
|
</code-example>
|
||||||
|
|
||||||
|
The following `devDependencies` are provided in the default `package.json` file for a new Angular workspace.
|
||||||
|
|
||||||
|
|
||||||
**[@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.
|
Package name | Description
|
||||||
|
---------------------------------------- | -----------------------------------
|
||||||
|
[**@angular‑devkit/<br />build‑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‑cli** | The Angular compiler, which is invoked by the Angular CLI's `ng build` and `ng serve` commands.
|
||||||
|
**@angular/<br />language‑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.
|
||||||
|
|
||||||
|
|
||||||
**[@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.
|
## Related information
|
||||||
For example, see the [Angular language service extension for VS Code](https://marketplace.visualstudio.com/items?itemName=Angular.ng-template)
|
|
||||||
|
|
||||||
|
For information about how the Angular CLI handles packages see the following guides:
|
||||||
**@types/... **: TypeScript definition files for 3rd party libraries such as Jasmine and Node.js.
|
|
||||||
|
* [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.
|
||||||
**[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.
|
|
||||||
|
|
||||||
|
|
||||||
## So many packages! So many files!
|
|
||||||
|
|
||||||
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,
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
See the [Deployment](guide/deployment) to learn more.
|
|
|
@ -517,8 +517,8 @@
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"url": "guide/npm-packages",
|
"url": "guide/npm-packages",
|
||||||
"title": "Packages",
|
"title": "npm Dependencies",
|
||||||
"tooltip": "Explanation of npm packages installed into a project by default."
|
"tooltip": "Description of npm packages required at development time and at runtime."
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"url": "guide/typescript-configuration",
|
"url": "guide/typescript-configuration",
|
||||||
|
|
Loading…
Reference in New Issue