docs: workspaces

Adds docs on workspaces, explaining its basic concept and how to use it.

3 files changed, 125 insertions, 1 deletions

diff --git a/docs/content/cli-commands/npm-install.md b/docs/content/cli-commands/npm-install.md
index a76518432..5ffb96f68 100644
--- a/docs/content/cli-commands/npm-install.md
+++ b/docs/content/cli-commands/npm-install.md
@@ -34,7 +34,6 @@ package has a package-lock, or an npm shrinkwrap file, or a yarn lock file, the
 installation of dependencies will be driven by that, respecting the following
 order of precedence:
 
-* `node_modules/.package-lock.json`
 * `npm-shrinkwrap.json`
 * `package-lock.json`
 * `yarn.lock`
@@ -495,3 +494,4 @@ specific folder structures that npm creates.
 * [npm uninstall](/cli-commands/uninstall)
 * [npm shrinkwrap](/cli-commands/shrinkwrap)
 * [package.json](/configuring-npm/package-json)
+* [workspaces](/using-npm/workspaces)
diff --git a/docs/content/configuring-npm/package-json.md b/docs/content/configuring-npm/package-json.md
index b872dac31..794c7ad7d 100644
--- a/docs/content/configuring-npm/package-json.md
+++ b/docs/content/configuring-npm/package-json.md
@@ -886,6 +886,31 @@ probably matter for the purposes of publishing.
 See [`config`](/using-npm/config) to see the list of config options that can be
 overridden.
 
+### workspaces
+
+The optional `workspaces` field is an array of file patterns that describes
+locations within the local file system that the install client should look up
+to find each [workspace](/using-npm/workspaces) that needs to be symlinked to
+the top level `node_modules` folder.
+
+It can describe either the direct paths of the folders to be used as
+workspaces or it can define globs that will resolve to these same folders.
+
+In the following example, all folders located inside the folder `./packages`
+will be treated as workspaces as long as they have valid `package.json` files
+inside them:
+
+```json
+{
+  "name": "workspace-example",
+  "workspaces": [
+    "./packages/*"
+  ]
+}
+```
+
+See [`workspaces`](/using-npm/workspaces) for more examples.
+
 ### DEFAULT VALUES
 
 npm will default some values based on package contents.
@@ -910,6 +935,7 @@ npm will default some values based on package contents.
 ### SEE ALSO
 
 * [semver](/using-npm/semver)
+* [workspaces](/using-npm/workspaces)
 * [npm init](/cli-commands/init)
 * [npm version](/cli-commands/version)
 * [npm config](/cli-commands/config)
diff --git a/docs/content/using-npm/workspaces.md b/docs/content/using-npm/workspaces.md
new file mode 100644
index 000000000..1f7086f0c
--- /dev/null
+++ b/docs/content/using-npm/workspaces.md
@@ -0,0 +1,98 @@
+---
+section: using-npm
+title: workspaces
+description: Working with workspaces
+---
+# scope(7)
+
+## Workspaces
+
+### Description
+
+**Workspaces** is a generic term that refers to the set of features in the
+npm cli that provides support to managing multiple packages from your local
+files system from within a singular top-level, root package.
+
+This set of features makes up for a much more streamlined workflow handling
+linked packages from the local file system. Automating the linking process
+as part of `npm install` and avoiding manually having to use `npm link` in
+order to add references to packages that should be symlinked into the current
+`node_modules` folder.
+
+We also refer to these packages being auto-symlinked during `npm install` as a
+single **workspace**, meaning it's a nested package within the current local
+file system that is explicitly defined in the [`package.json`](/using-npm/package-json)
+`workspaces` configuration.
+
+### Installing workspaces
+
+Workspaces are usually defined via the `workspaces` property of the
+[`package.json`](/using-npm/package-json) file, e.g:
+
+```json
+{
+  "name": "my-workspaces-powered-project",
+  "workspaces": [
+    "workspace-a"
+  ]
+}
+```
+
+Given the above `package.json` example living at a current working
+directory `.` that contains a folder named `workspace-a` that disposes
+of a `package.json` inside it, defining a nodejs package, e.g:
+
+```
+.
++-- package.json
+`-- workspace-a
+   `-- package.json
+```
+
+The expected result once running `npm install` in this current working
+directory `.` is that the folder `workspace-a` will get symlinked to the
+`node_modules` folder of the current working dir.
+
+Below is a post `npm install` example, given that same previous example
+structure of files and folders:
+
+```
+.
++-- node_modules
+|  `-- workspace-a -> ../workspace-a
++-- package-lock.json
++-- package.json
+`-- workspace-a
+   `-- package.json
+```
+
+### Using workspaces
+
+Given the [specifities of how Node.js handles module resolution](https://nodejs.org/dist/latest-v14.x/docs/api/modules.html#modules_all_together) it's possible to consume any defined workspace
+by it's declared `package.json` `name`. Continuing from the example defined
+above, let's also create a Node.js script that will require the `workspace-a`
+example module, e.g:
+
+```
+// ./workspace-a/index.js
+module.exports = 'a'
+
+// ./lib/index.js
+const moduleA = require('workspace-a')
+console.log(moduleA) // -> a
+```
+
+When running it with:
+
+`node lib/index.js`
+
+This demonstrates how the nature of `node_modules` resolution allows for
+**workspaces** to enable a portable workflow for requiring each **workspace**
+in such a way that is also easy to [publish](/cli-commands/publish) these
+nested workspaces to be consumed elsewhere.
+
+### See also
+
+* [npm install](/cli-commands/install)
+* [npm publish](/cli-commands/publish)
+