Skip to content

Isaacs/docs lockfile #2475

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

Closed
wants to merge 3 commits into from
Closed

Isaacs/docs lockfile #2475

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1bc76d5
docs: update package-lock.json doc
isaacs Jan 12, 2021
03ccc97
update doc for npm-shrinkwrap.json
isaacs Jan 12, 2021
09df82c
doc: corrections and updates to shrinkwrap and package.json docs
isaacs Jan 12, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion docs/content/commands/npm-audit.md
View file
Open in desktop
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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

isn’t this still relevant, since npm audit still unfortunately requires a lockfile?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It just felt somewhat out of place, especially in the "configuring-npm" section, since it's much more conceptual.

Maybe it should be brought back in (and updated for correctness) in the using-npm section?

Also, maybe Arborist.audit() should do this.loadVirtual().catch(() => this.loadActual()) or .catch(() => this.buildIdealTree()), so a lockfile isn't required? 🤔

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Screw the docs, yes please do that :-D

* [config](/using-npm/config)
2 changes: 1 addition & 1 deletion docs/content/commands/npm-ci.md
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the hard wraps make it very awkward to review and presumably edit the text, and also makes git diffs much noisier; is there a reason it doesn’t soft wrap?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We do hard wraps everywhere else in the docs. In vim, it definitely makes it easier to edit, and gq{ will re-wrap an entire paragraph easily. I typically view markdown diffs with the "rich diff" mode, so whitespace is ignored and you can just read the rendered text more easily.

I would only be mildly opposed to moving to soft wraps (since I'd have to retrain some vim settings and muscle memory) but that's a separate conversation, and in the meantime, consistency is the way to go, imo.

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/
20 changes: 12 additions & 8 deletions ...ontent/configuring-npm/shrinkwrap-json.md → ...nt/configuring-npm/npm-shrinkwrap-json.md
View file
Open in desktop
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
View file
Open in desktop
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