4 files changed, 60 insertions, 19 deletions
diff --git a/deps/npm/doc/files/npm-folders.md b/deps/npm/doc/files/npm-folders.md
index 74c7883443..456cb58bc8 100644
--- a/deps/npm/doc/files/npm-folders.md
+++ b/deps/npm/doc/files/npm-folders.md
@@ -68,7 +68,7 @@ Man pages are not installed on Windows systems.
 ### Cache
 
 See `npm-cache(1)`.  Cache files are stored in `~/.npm` on Posix, or
-`~/npm-cache` on Windows.
+`%AppData%/npm-cache` on Windows.
 
 This is controlled by the `cache` configuration param.
 
diff --git a/deps/npm/doc/files/npm-package-locks.md b/deps/npm/doc/files/npm-package-locks.md
index c57fc85658..cbb62bdc38 100644
--- a/deps/npm/doc/files/npm-package-locks.md
+++ b/deps/npm/doc/files/npm-package-locks.md
@@ -136,6 +136,25 @@ on. Additionally, the diffs from these changes are human-readable and will
 inform you of any changes npm has made to your `node_modules`, so you can notice
 if any transitive dependencies were updated, hoisted, etc.
 
+### Resolving lockfile conflicts
+
+Occasionally, two separate npm install will create package locks that cause
+merge conflicts in source control systems. As of `npm@5.7.0`, these conflicts
+can be resolved by manually fixing any `package.json` conflicts, and then
+running `npm install [--package-lock-only]` again. npm will automatically
+resolve any conflicts for you and write a merged package lock that includes all
+the dependencies from both branches in a reasonable tree. If
+`--package-lock-only` is provided, it will do this without also modifying your
+local `node_modules/`.
+
+To make this process seamless on git, consider installing
+[`npm-merge-driver`](https://npm.im/npm-merge-driver), which will teach git how
+to do this itself without any user interaction. In short: `$ npx
+npm-merge-driver install -g` will let you do this, and even works with
+pre-`npm@5.7.0` versions of npm 5, albeit a bit more noisily. Note that if
+`package.json` itself conflicts, you will have to resolve that by hand and run
+`npm install` manually, even with the merge driver.
+
 ## SEE ALSO
 
 * https://medium.com/@sdboyer/so-you-want-to-write-a-package-manager-4ae9c17d9527
diff --git a/deps/npm/doc/files/package-lock.json.md b/deps/npm/doc/files/package-lock.json.md
index 4c134fc229..1b4ba93497 100644
--- a/deps/npm/doc/files/package-lock.json.md
+++ b/deps/npm/doc/files/package-lock.json.md
@@ -120,6 +120,15 @@ transitive dependency of a non-optional dependency of the top level.
 All optional dependencies should be included even if they're uninstallable
 on the current platform.
 
+
+#### requires
+
+This is a mapping of module name to version.  This is a list of everything
+this module requires, regardless of where it will be installed.  The version
+should match via normal matching rules a dependency either in our
+`dependencies` or in a level higher than us.
+
+
 #### dependencies
 
 The dependencies of this dependency, exactly as at the top level.
@@ -128,5 +137,6 @@ The dependencies of this dependency, exactly as at the top level.
 
 * npm-shrinkwrap(1)
 * npm-shrinkwrap.json(5)
+* npm-package-locks(5)
 * package.json(5)
 * npm-install(1)
diff --git a/deps/npm/doc/files/package.json.md b/deps/npm/doc/files/package.json.md
index d91984d1d4..2ad3bcf68c 100644
--- a/deps/npm/doc/files/package.json.md
+++ b/deps/npm/doc/files/package.json.md
@@ -11,11 +11,11 @@ settings described in `npm-config(7)`.
 
 ## name
 
-The *most* important things in your package.json are the name and version fields.
-Those are actually required, and your package won't install without
-them.  The name and version together form an identifier that is assumed
-to be completely unique.  Changes to the package should come along with
-changes to the version.
+If you plan to publish your package, the *most* important things in your
+package.json are the name and version fields as they will be required. The name
+and version together form an identifier that is assumed to be completely unique.
+Changes to the package should come along with changes to the version. If you don't
+plan to publish your package, the name and version fields are optional.
 
 The name is what your thing is called.
 
@@ -44,11 +44,11 @@ A name can be optionally prefixed by a scope, e.g. `@myorg/mypackage`. See
 
 ## version
 
-The *most* important things in your package.json are the name and version fields.
-Those are actually required, and your package won't install without
-them.  The name and version together form an identifier that is assumed
-to be completely unique.  Changes to the package should come along with
-changes to the version.
+If you plan to publish your package, the *most* important things in your
+package.json are the name and version fields as they will be required. The name
+and version together form an identifier that is assumed to be completely unique.
+Changes to the package should come along with changes to the version. If you don't
+plan to publish your package, the name and version fields are optional.
 
 Version must be parseable by
 [node-semver](https://github.com/isaacs/node-semver), which is bundled
@@ -70,6 +70,10 @@ discover your package as it's listed in `npm search`.
 
 The url to the project homepage.
 
+Example:
+
+    "homepage": "https://github.com/owner/project#readme"
+
 ## bugs
 
 The url to your project's issue tracker and / or the email address to which
@@ -168,13 +172,15 @@ npm also sets a top-level "maintainers" field with your npm user info.
 
 ## files
 
-The optional "files" field is an array of file patterns that describes
+The optional `files` field is an array of file patterns that describes
 the entries to be included when your package is installed as a
-dependency. If the files array is omitted, everything except
-automatically-excluded files will be included in your publish. If you
-name a folder in the array, then it will also include the files inside
-that folder (unless they would be ignored by another rule in this
-section.).
+dependency. File patterns follow a similar syntax to `.gitignore`, but
+reversed: including a file, directory, or glob pattern (`*`, `**/*`, and such)
+will make it so that file is included in the tarball when it's packed. Omitting
+the field will make it default to `["*"]`, which means it will include all files.
+
+Some special files and directories are also included or excluded regardless of
+whether they exist in the `files` array (see below).
 
 You can also provide a `.npmignore` file in the root of your package or
 in subdirectories, which will keep files from being included. At the
@@ -226,6 +232,12 @@ This should be a module ID relative to the root of your package folder.
 For most modules, it makes the most sense to have a main script and often not
 much else.
 
+## browser
+
+If your module is meant to be used client-side the browser field should be
+used instead of the main field. This is helpful to hint users that it might
+rely on primitives that aren't available in Node.js modules. (e.g. `window`)
+
 ## bin
 
 A lot of packages have one or more executable files that they'd like to
@@ -745,8 +757,8 @@ especially handy if you want to set the tag, registry or access, so that
 you can ensure that a given package is not tagged with "latest", published
 to the global public registry or that a scoped module is private by default.
 
-Any config values can be overridden, but of course only "tag", "registry" and
-"access" probably matter for the purposes of publishing.
+Any config values can be overridden, but only "tag", "registry" and "access"
+probably matter for the purposes of publishing.
 
 See `npm-config(7)` to see the list of config options that can be
 overridden.