Skip to content

Commit

Permalink
fix(docs): update package-lock.json docs
Browse files Browse the repository at this point in the history
PR-URL: #2475
Credit: @isaacs
Close: #2475
Reviewed-by: @wraithgar
  • Loading branch information
isaacs authored and wraithgar committed Jan 14, 2021
1 parent cfdcf32 commit acd5b06
Show file tree
Hide file tree
Showing 9 changed files with 666 additions and 655 deletions.
1 change: 0 additions & 1 deletion docs/content/commands/npm-audit.md
Original file line number Diff line number Diff line change
Expand Up @@ -190,5 +190,4 @@ $ npm audit --audit-level=moderate
### See Also

* [npm install](/commands/npm-install)
* [package-locks](/configuring-npm/package-locks)
* [config](/using-npm/config)
2 changes: 1 addition & 1 deletion docs/content/commands/npm-ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,4 +68,4 @@ cache:
### See Also

* [npm install](/commands/npm-install)
* [package-locks](/configuring-npm/package-locks)
* [package-lock.json](/configuring-npm/package-lock-json)
14 changes: 7 additions & 7 deletions docs/content/commands/npm-shrinkwrap.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,18 +13,18 @@ npm shrinkwrap
### Description

This command repurposes `package-lock.json` into a publishable
`npm-shrinkwrap.json` or simply creates a new one. The file created and updated
by this command will then take precedence over any other existing or future
`package-lock.json` files. For a detailed explanation of the design and purpose
of package locks in npm, see [package-locks](/configuring-npm/package-locks).
`npm-shrinkwrap.json` or simply creates a new one. The file created and
updated by this command will then take precedence over any other existing
or future `package-lock.json` files. For a detailed explanation of the
design and purpose of package locks in npm, see
[package-lock-json](/configuring-npm/package-lock-json).

### See Also

* [npm install](/commands/npm-install)
* [npm run-script](/commands/npm-run-script)
* [npm scripts](/using-npm/scripts)
* [package.js](/configuring-npm/package-json)
* [package-locks](/configuring-npm/package-locks)
* [package.json](/configuring-npm/package-json)
* [package-lock.json](/configuring-npm/package-lock-json)
* [shrinkwrap.json](/configuring-npm/shrinkwrap-json)
* [npm-shrinkwrap.json](/configuring-npm/npm-shrinkwrap-json)
* [npm ls](/commands/npm-ls)
53 changes: 37 additions & 16 deletions docs/content/configuring-npm/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,27 @@ description: Download and install node and npm

### Description

To publish and install packages to and from the public npm registry, you must install Node.js and the npm command line interface using either a Node version manager or a Node installer. **We strongly recommend using a Node version manager to install Node.js and npm.** We do not recommend using a Node installer, since the Node installation process installs npm in a directory with local permissions and can cause permissions errors when you run npm packages globally.
To publish and install packages to and from the public npm registry, you
must install Node.js and the npm command line interface using either a Node
version manager or a Node installer. **We strongly recommend using a Node
version manager to install Node.js and npm.** We do not recommend using a
Node installer, since the Node installation process installs npm in a
directory with local permissions and can cause permissions errors when you
run npm packages globally.

### Overview

- [Checking your version of npm and Node.js](#checking-your-version-of-npm-and-node-js)
- [Using a Node version manager to install Node.js and npm](#using-a-node-version-manager-to-install-node-js-and-npm)
- [Using a Node installer to install Node.js and npm](#using-a-node-installer-to-install-node-js-and-npm)
- [Checking your version of npm and
Node.js](#checking-your-version-of-npm-and-node-js)
- [Using a Node version manager to install Node.js and
npm](#using-a-node-version-manager-to-install-node-js-and-npm)
- [Using a Node installer to install Node.js and
npm](#using-a-node-installer-to-install-node-js-and-npm)

### Checking your version of npm and Node.js

To see if you already have Node.js and npm installed and check the installed version, run the following commands:
To see if you already have Node.js and npm installed and check the
installed version, run the following commands:

```
node -v
Expand All @@ -25,7 +35,10 @@ npm -v

### Using a Node version manager to install Node.js and npm

Node version managers allow you to install and switch between multiple versions of Node.js and npm on your system so you can test your applications on multiple versions of npm to ensure they work for users on different versions.
Node version managers allow you to install and switch between multiple
versions of Node.js and npm on your system so you can test your
applications on multiple versions of npm to ensure they work for users on
different versions.

#### OSX or Linux Node version managers

Expand All @@ -39,28 +52,36 @@ Node version managers allow you to install and switch between multiple versions

### Using a Node installer to install Node.js and npm

If you are unable to use a Node version manager, you can use a Node installer to install both Node.js and npm on your system.
If you are unable to use a Node version manager, you can use a Node
installer to install both Node.js and npm on your system.

* [Node.js installer](https://nodejs.org/en/download/)
* [NodeSource installer](https://github.com/nodesource/distributions). If you use Linux, we recommend that you use a NodeSource installer.
* [NodeSource installer](https://github.com/nodesource/distributions). If
you use Linux, we recommend that you use a NodeSource installer.

#### OS X or Windows Node installers

If you're using OS X or Windows, use one of the installers from the [Node.js download page](https://nodejs.org/en/download/). Be sure to install the version labeled **LTS**. Other versions have not yet been tested with npm.
If you're using OS X or Windows, use one of the installers from the
[Node.js download page](https://nodejs.org/en/download/). Be sure to
install the version labeled **LTS**. Other versions have not yet been
tested with npm.

#### Linux or other operating systems Node installers

If you're using Linux or another operating system, use one of the following installers:
If you're using Linux or another operating system, use one of the following
installers:

- [NodeSource installer](https://github.com/nodesource/distributions) (recommended)
- One of the installers on the [Node.js download page](https://nodejs.org/en/download/)

Or see [this page](https://nodejs.org/en/download/package-manager/) to install npm for Linux in the way many Linux developers prefer.
- [NodeSource installer](https://github.com/nodesource/distributions)
(recommended)
- One of the installers on the [Node.js download
page](https://nodejs.org/en/download/)

Or see [this page](https://nodejs.org/en/download/package-manager/) to
install npm for Linux in the way many Linux developers prefer.

#### Less-common operating systems

For more information on installing Node.js on a variety of operating systems, see [this page][pkg-mgr].

For more information on installing Node.js on a variety of operating
systems, see [this page][pkg-mgr].

[pkg-mgr]: https://nodejs.org/en/download/package-manager/
Original file line number Diff line number Diff line change
@@ -1,26 +1,30 @@
---
title: shrinkwrap.json
title: npm-shrinkwrap.json
section: 5
description: A publishable lockfile
---

### Description

`npm-shrinkwrap.json` is a file created by [`npm shrinkwrap`](/commands/npm-shrinkwrap). It is identical to
`npm-shrinkwrap.json` is a file created by [`npm
shrinkwrap`](/commands/npm-shrinkwrap). It is identical to
`package-lock.json`, with one major caveat: Unlike `package-lock.json`,
`npm-shrinkwrap.json` may be included when publishing a package.

The recommended use-case for `npm-shrinkwrap.json` is applications deployed
through the publishing process on the registry: for example, daemons and
command-line tools intended as global installs or `devDependencies`. It's
strongly discouraged for library authors to publish this file, since that would
prevent end users from having control over transitive dependency updates.
strongly discouraged for library authors to publish this file, since that
would prevent end users from having control over transitive dependency
updates.

Additionally, if both `package-lock.json` and `npm-shrinkwrap.json` are present
in a package root, `package-lock.json` will be ignored in favor of this file.
If both `package-lock.json` and `npm-shrinkwrap.json` are present in a
package root, `npm-shrinkwrap.json` will be preferred over the
`package-lock.json` file.

For full details and description of the `npm-shrinkwrap.json` file format, refer
to the manual page for [package-lock.json](/configuring-npm/package-lock-json).
For full details and description of the `npm-shrinkwrap.json` file format,
refer to the manual page for
[package-lock.json](/configuring-npm/package-lock-json).

### See also

Expand Down
53 changes: 27 additions & 26 deletions docs/content/configuring-npm/npmrc.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,14 @@ description: The npm config files

### Description

npm gets its config settings from the command line, environment
variables, and `npmrc` files.
npm gets its config settings from the command line, environment variables,
and `npmrc` files.

The `npm config` command can be used to update and edit the contents
of the user and global npmrc files.
The `npm config` command can be used to update and edit the contents of the
user and global npmrc files.

For a list of available configuration options, see [config](/using-npm/config).
For a list of available configuration options, see
[config](/using-npm/config).

### Files

Expand All @@ -23,20 +24,19 @@ The four relevant files are:
* global config file ($PREFIX/etc/npmrc)
* npm builtin config file (/path/to/npm/npmrc)

All npm config files are an ini-formatted list of `key = value`
parameters. Environment variables can be replaced using
`${VARIABLE_NAME}`. For example:
All npm config files are an ini-formatted list of `key = value` parameters.
Environment variables can be replaced using `${VARIABLE_NAME}`. For
example:

```bash
prefix = ${HOME}/.npm-packages
```

Each of these files is loaded, and config options are resolved in
priority order. For example, a setting in the userconfig file would
override the setting in the globalconfig file.
Each of these files is loaded, and config options are resolved in priority
order. For example, a setting in the userconfig file would override the
setting in the globalconfig file.

Array values are specified by adding "[]" after the key name. For
example:
Array values are specified by adding "[]" after the key name. For example:

```bash
key[] = "first value"
Expand All @@ -45,7 +45,9 @@ key[] = "second value"

#### Comments

Lines in `.npmrc` files are interpreted as comments when they begin with a `;` or `#` character. `.npmrc` files are parsed by [npm/ini](https://github.com/npm/ini), which specifies this comment syntax.
Lines in `.npmrc` files are interpreted as comments when they begin with a
`;` or `#` character. `.npmrc` files are parsed by
[npm/ini](https://github.com/npm/ini), which specifies this comment syntax.

For example:

Expand All @@ -61,34 +63,33 @@ When working locally in a project, a `.npmrc` file in the root of the
project (ie, a sibling of `node_modules` and `package.json`) will set
config values specific to this project.

Note that this only applies to the root of the project that you're
running npm in. It has no effect when your module is published. For
example, you can't publish a module that forces itself to install
globally, or in a different location.
Note that this only applies to the root of the project that you're running
npm in. It has no effect when your module is published. For example, you
can't publish a module that forces itself to install globally, or in a
different location.

Additionally, this file is not read in global mode, such as when running
`npm install -g`.

#### Per-user config file

`$HOME/.npmrc` (or the `userconfig` param, if set in the environment
or on the command line)
`$HOME/.npmrc` (or the `userconfig` param, if set in the environment or on
the command line)

#### Global config file

`$PREFIX/etc/npmrc` (or the `globalconfig` param, if set above):
This file is an ini-file formatted list of `key = value` parameters.
Environment variables can be replaced as above.
`$PREFIX/etc/npmrc` (or the `globalconfig` param, if set above): This file
is an ini-file formatted list of `key = value` parameters. Environment
variables can be replaced as above.

#### Built-in config file

`path/to/npm/itself/npmrc`

This is an unchangeable "builtin" configuration file that npm keeps
consistent across updates. Set fields in here using the `./configure`
script that comes with npm. This is primarily for distribution
maintainers to override default configs in a standard and consistent
manner.
script that comes with npm. This is primarily for distribution maintainers
to override default configs in a standard and consistent manner.

### See also

Expand Down
Loading

0 comments on commit acd5b06

Please sign in to comment.