Skip to content
This repository was archived by the owner on Dec 4, 2017. It is now read-only.

Commit 66562c8

Browse files
kapunahelewongjuleskremer
authored andcommitted
docs(npm-packages): edit copy to guidelines (#3361)
1 parent a6478bc commit 66562c8

File tree

1 file changed

+112
-107
lines changed

1 file changed

+112
-107
lines changed

public/docs/ts/latest/guide/npm-packages.jade

Lines changed: 112 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -5,215 +5,220 @@ include ../_util-fns
55
These packages are maintained and installed with the Node Package Manager (<a href="https://docs.npmjs.com/" target="_blank">npm</a>).
66
.l-sub-section
77
:marked
8-
Node.js and npm are essential to Angular development.
9-
8+
Node.js and npm are essential to Angular development.
9+
1010
<a href="https://docs.npmjs.com/getting-started/installing-node" target="_blank" title="Installing Node.js and updating npm">
1111
Get them now</a> if they're not already installed on your machine.
12-
12+
1313
**Verify that you are running node `v4.x.x` or higher and npm `3.x.x` or higher**
1414
by running the commands `node -v` and `npm -v` in a terminal/console window.
1515
Older versions produce errors.
1616

17-
We recommend [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.
17+
Consider using [nvm](https://github.com/creationix/nvm) for managing multiple
18+
versions of node and npm. You may need [nvm](https://github.com/creationix/nvm) if
19+
you already have projects running on your machine that use other versions of node and npm.
1820

1921
:marked
20-
We recommend a comprehensive starter-set of packages as specified in the `dependencies` and `devDependencies`
21-
sections of the <a href="https://docs.npmjs.com/files/package.json" target="_blank">package.json</a> file
22-
installed as described during [Setup](setup.html).
23-
:marked
24-
You can use other packages but we recommend *this particular set* to start with because (a) they work well together and
25-
(b) they include everything you'll need to build and run the sample applications in this series.
22+
During [Setup](setup.html), a <a href="https://docs.npmjs.com/files/package.json" target="_blank">package.json</a>
23+
file is installed with a comprehensive starter set of
24+
packages as specified in the `dependencies` and `devDependencies` sections.
25+
26+
You can use other packages but the packages in _this particular set_ work well together and include
27+
everything you need to build and run the sample applications in this series.
28+
2629
.l-sub-section
2730
:marked
2831
Note: A cookbook or guide page may require an additional library such as *jQuery*.
2932
:marked
30-
You'll install more than you need for QuickStart.
31-
No worries!
33+
You'll install more than you need for the QuickStart guide.
34+
No worries!
3235
You only serve to the client those packages that the application actually requests.
33-
36+
3437
This page explains what each package does. You can make substitutions later to suit your tastes and experience.
35-
38+
3639
.l-main-section
3740
:marked
3841
## *dependencies* and *devDependencies*
39-
The `package.json` includes two sets of packages,
42+
The `package.json` includes two sets of packages,
4043
[dependencies](#dependencies) and [devDependencies](#dev-dependencies).
41-
42-
The *dependencies* are essential to *running* the application.
43-
The *devDependencies* are only necessary to *develop* the application.
44+
45+
The *dependencies* are essential to *running* the application.
46+
The *devDependencies* are only necessary to *develop* the application.
4447
You can exclude them from production installations by adding `--production` to the install command, as follows:
4548
code-example(format="." language="bash").
4649
npm install my-application --production
47-
50+
4851
a(id="dependencies")
4952
.l-main-section
5053
:marked
5154
## *dependencies*
5255
The `dependencies` section of `package.json` contains:
53-
54-
* ***Features*** - Feature packages give the application framework and utility capabilities.
55-
56-
* ***Polyfills*** - Polyfills plug gaps in the browser's JavaScript implementation.
57-
58-
* ***Other*** - Other libraries that support the application such as `bootstrap` for HTML widgets and styling.
59-
56+
57+
* ***Features***: Feature packages give the application framework and utility capabilities.
58+
59+
* ***Polyfills***: Polyfills plug gaps in the browser's JavaScript implementation.
60+
61+
* ***Other***: Other libraries that support the application such as `bootstrap` for HTML widgets and styling.
62+
6063
.l-main-section
6164
:marked
6265
### Feature Packages
63-
64-
***@angular/core*** - Critical runtime parts of the framework needed by every application.
66+
67+
***@angular/core***: Critical runtime parts of the framework needed by every application.
6568
Includes all metadata decorators, `Component`, `Directive`, dependency injection, and the component lifecycle hooks.
66-
67-
***@angular/common*** - The commonly needed services, pipes, and directives provided by the Angular team.
68-
69-
***@angular/compiler*** - Angular's *Template Compiler*.
70-
It understands templates and can convert them to code that makes the application run and render.
69+
70+
***@angular/common***: The commonly needed services, pipes, and directives provided by the Angular team.
71+
72+
***@angular/compiler***: Angular's *Template Compiler*.
73+
It understands templates and can convert them to code that makes the application run and render.
7174
Typically you don’t interact with the compiler directly; rather, you use it indirectly via `platform-browser-dynamic` or the offline template compiler.
72-
73-
***@angular/platform-browser*** - Everything DOM and browser related, especially the pieces that help render into DOM.
74-
This package also includes the bootstrapStatic method for bootstrapping applications for production builds that pre-compile templates offline.
75-
76-
***@angular/platform-browser-dynamic*** - Includes [Providers](../api/core/index/Provider-type-alias.html) and a [bootstrap](ngmodule.html#bootstrap) method for applications that
75+
76+
***@angular/platform-browser***: Everything DOM and browser related, especially
77+
the pieces that help render into the DOM.
78+
This package also includes the `bootstrapStatic()` method
79+
for bootstrapping applications for production builds that pre-compile templates offline.
80+
81+
***@angular/platform-browser-dynamic***: Includes [Providers](../api/core/index/Provider-type-alias.html)
82+
and a [bootstrap](ngmodule.html#bootstrap) method for applications that
7783
compile templates on the client. Don’t use offline compilation.
7884
Use this package for bootstrapping during development and for bootstrapping plunker samples.
79-
80-
***@angular/http*** - Angular's http client.
81-
82-
***@angular/router*** - Component router.
83-
84-
***@angular/upgrade*** - Set of utilities for upgrading AngularJS applications to Angular.
85-
86-
***[system.js](https://github.com/systemjs/systemjs)*** - A dynamic module loader compatible with the
85+
86+
***@angular/http***: Angular's HTTP client.
87+
88+
***@angular/router***: Component router.
89+
90+
***@angular/upgrade***: Set of utilities for upgrading AngularJS applications to Angular.
91+
92+
***[system.js](https://github.com/systemjs/systemjs)***: A dynamic module loader compatible with the
8793
[ES2015 module](http://www.2ality.com/2014/09/es6-modules-final.html) specification.
8894
Other viable choices include the well-regarded [webpack](https://webpack.github.io/).
89-
95+
9096
Your future applications are likely to require additional packages that provide
9197
HTML controls, themes, data access, and various utilities.
92-
98+
9399

94100
a(id="polyfills")
95101
.l-main-section
96102
:marked
97103
### Polyfill packages
98-
104+
99105
Angular requires certain [polyfills](https://en.wikipedia.org/wiki/Polyfill) in the application environment.
100106
Install these polyfills using the npm packages that Angular lists in the *peerDependencies* section of its `package.json`.
101-
107+
102108
You must list these packages in the `dependencies` section of your own `package.json`.
103-
109+
104110
.l-sub-section
105111
:marked
106112
For background on this requirement, see [Why peerDependencies?](#why-peer-dependencies).
107113
:marked
108-
***core-js*** - Patches the global context (window) with essential features of ES2015 (ES6).
109-
You may substitute an alternative polyfill that provides the same core APIs.
114+
***core-js***: Patches the global context (window) with essential features of ES2015 (ES6).
115+
You may substitute an alternative polyfill that provides the same core APIs.
110116
When these APIs are implemented by the major browsers, this dependency will become unnecessary.
111-
112-
***rxjs*** - A polyfill for the [Observables specification](https://github.com/zenparsing/es-observable) currently before the
117+
118+
***rxjs***: A polyfill for the [Observables specification](https://github.com/zenparsing/es-observable) currently before the
113119
[TC39](http://www.ecma-international.org/memento/TC39.htm) committee that determines standards for the JavaScript language.
114-
You can pick a preferred version of *rxjs* (within a compatible version range)
120+
You can pick a preferred version of *rxjs* (within a compatible version range)
115121
without waiting for Angular updates.
116-
117-
***zone.js*** - A polyfill for the [Zone specification](https://gist.github.com/mhevery/63fdcdf7c65886051d55) currently before the
122+
123+
***zone.js***: A polyfill for the [Zone specification](https://gist.github.com/mhevery/63fdcdf7c65886051d55) currently before the
118124
[TC39](http://www.ecma-international.org/memento/TC39.htm) committee that determines standards for the JavaScript language.
119-
You can pick a preferred version of *zone.js* to use (within a compatible version range)
125+
You can pick a preferred version of *zone.js* to use (within a compatible version range)
120126
without waiting for Angular updates.
121127

122128
a(id="other")
123129
.l-main-section
124130
:marked
125131
### Other helper libraries
126-
127-
***angular-in-memory-web-api*** - An Angular-supported library that simulates a remote server's web api
128-
without requiring an actual server or real http calls.
129-
Good for demos, samples, and early stage development (before we even have a server).
130-
Read about it in the [Http Client](server-communication.html#appendix-tour-of-heroes-in-memory-server) page.
131-
132-
***bootstrap*** - [Bootstrap](http://getbootstrap.com/) is a popular HTML and CSS framework for designing responsive web apps.
132+
133+
***angular-in-memory-web-api***: An Angular-supported library that simulates a remote server's web api
134+
without requiring an actual server or real HTTP calls.
135+
Good for demos, samples, and early stage development (before you even have a server).
136+
Read about it in the [HTTP Client](server-communication.html#in-mem-web-api) page.
137+
138+
***bootstrap***: [Bootstrap](http://getbootstrap.com/) is a popular HTML and CSS framework for designing responsive web apps.
133139
Some of the samples improve their appearance with *bootstrap*.
134-
140+
135141
a(id="dev-dependencies")
136142
.l-main-section
137143
:marked
138144
## *devDependencies*
139145
The packages listed in the *devDependencies* section of the `package.json` help you develop the application.
140146
You don't have to deploy them with the production application although there is no harm in doing so.
141147

142-
***[concurrently](https://www.npmjs.com/package/concurrently)*** -
148+
***[concurrently](https://www.npmjs.com/package/concurrently)***:
143149
A utility to run multiple *npm* commands concurrently on OS/X, Windows, and Linux operating systems.
144-
145-
***[lite-server](https://www.npmjs.com/package/lite-server)*** -
146-
A light-weight, static file server, by [John Papa](http://johnpapa.net/)
150+
151+
***[lite-server](https://www.npmjs.com/package/lite-server)***:
152+
A light-weight, static file server, by [John Papa](http://johnpapa.net/)
147153
with excellent support for Angular apps that use routing.
148-
149-
***[typescript](https://www.npmjs.com/package/typescript)*** -
154+
155+
***[typescript](https://www.npmjs.com/package/typescript)***:
150156
the TypeScript language server, including the *tsc* TypeScript compiler.
151-
152-
***@types/\**** - TypeScript definition files.
153-
Learn more about it in the [TypeScript Configuration](typescript-configuration.html#typings) chapter.
157+
158+
***@types/\****: TypeScript definition files.
159+
Learn more about it in the [TypeScript Configuration](typescript-configuration.html#typings) guide.
154160

155161
.l-main-section
156162
a(id="why-peer-dependencies")
157163
:marked
158164
## Why *peerDependencies*?
159-
160-
There isn't a *peerDependencies* section in the QuickStart `package.json`.
161-
But Angular has a *peerDependencies* section in
162-
*its* package.json, which has important consequences for your application.
163-
164-
It explains why you load the [polyfill](#polyfills) *dependency* packages in the QuickStart `package.json`,
165+
166+
There isn't a [*peerDependencies*](https://nodejs.org/en/blog/npm/peer-dependencies/) section in the QuickStart `package.json`.
167+
But Angular has a *peerDependencies* section in
168+
*its* `package.json`, which has important consequences for your application.
169+
170+
This section explains why you load the [polyfill](#polyfills) *dependency*
171+
packages in the QuickStart application's `package.json`,
165172
and why you'll need those packages in your own applications.
166-
167-
An explanation of [peer dependencies](https://nodejs.org/en/blog/npm/peer-dependencies/) follows.
168-
173+
169174
Packages depend on other packages. For example, your application depends on the Angular package.
170-
171-
Two packages, "A" and "B", could depend on the same third package "C".
175+
176+
Two packages, "A" and "B", could depend on the same third package "C".
172177
"A" and "B" might both list "C" among their *dependencies*.
173-
174-
What if "A" and "B" depend on different versions of "C" ("C1" and "C2"). The npm package system supports that.
178+
179+
What if "A" and "B" depend on different versions of "C" ("C1" and "C2"). The npm package system supports that.
175180
It installs "C1" in the `node_modules` folder for "A" and "C2" in the `node_modules` folder for "B".
176181
Now "A" and "B" have their own copies of "C" and they run without interferring with one another.
177-
182+
178183
But there is a problem. Package "A" may require the presence of "C1" without actually calling upon it directly.
179184
"A" may only work if *everyone is using "C1"*. It falls down if any part of the application relies on "C2".
180-
185+
181186
The solution is for "A" to declare that "C1" is a *peer dependency*.
182-
187+
183188
The difference between a `dependency` and a `peerDependency` is roughly this:
184-
189+
185190
>A **dependency** says, "I need this thing directly available to *me*."
186191
>
187192
>A **peerDependency** says, "If you want to use me, you need this thing available to *you*."
188-
189-
The Angular `package.json` specifies several *peer dependency* packages,
193+
194+
The Angular `package.json` specifies several *peer dependency* packages,
190195
each pinned to a particular version of a third-party package.
191196

192-
### We must install Angular's *peerDependencies* ourselves.
193-
197+
### You must install Angular's *peerDependencies* yourself.
198+
194199
When *npm* installs packages listed in *your* `dependencies` section,
195200
it also installs the packages listed within *their* packages `dependencies` sections.
196201
The process is recursive.
197-
202+
198203
However, as of version 3, *npm* does *not* install packages listed in *peerDependencies* sections.
199-
204+
200205
This means that when your application installs Angular, ***npm* doesn't automatically install
201206
the packages listed in Angular's *peerDependencies* section**.
202-
207+
203208
Fortunately, *npm* issues a warning (a) When any *peer dependencies* are missing, or (b)
204209
When the application or any of its other dependencies
205-
installs a different version of a *peer dependency*.
206-
210+
installs a different version of a *peer dependency*.
211+
207212
These warnings guard against accidental failures due to version mismatches.
208213
They leave you in control of package and version resolution.
209-
214+
210215
It is your responsibility to list all *peer dependency* packages **among your own *devDependencies***.
211-
216+
212217
.l-sub-section
213218
:marked
214219
#### The future of *peerDependencies*
215-
220+
216221
The Angular polyfill dependencies are hard requirements. Currently, there is no way to make them optional.
217-
218-
However, there is an npm feature request for "optional peerDependencies," which would allow you to model this relationship better.
222+
223+
However, there is an npm feature request for "optional peerDependencies," which would allow you to model this relationship better.
219224
When this feature request is implemented, Angular will switch from *peerDependencies* to *optionalPeerDependencies* for all polyfills.

0 commit comments

Comments
 (0)