From 052e977b9d071e1b3654976881d10cd3ddcba788 Mon Sep 17 00:00:00 2001
From: foxxyz <foxxyz@gmail.com>
Date: Thu, 17 Sep 2020 20:46:07 -0700
Subject: [PATCH] docs: add section on peerDependenciesMeta field in
 package.json (fixes #1247)

Credit: @foxxyz
Close: #1822
Fixes: #1247
Reviewed-by: @ruyadorno
---
 docs/content/configuring-npm/package-json.md | 24 ++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/content/configuring-npm/package-json.md b/docs/content/configuring-npm/package-json.md
index 74e2cbd11eec3..8b9b4ffbb1074 100644
--- a/docs/content/configuring-npm/package-json.md
+++ b/docs/content/configuring-npm/package-json.md
@@ -716,6 +716,30 @@ the host package's major version will break your plugin. Thus, if you've worked
 with every 1.x version of the host package, use `"^1.0"` or `"1.x"` to express
 this. If you depend on features introduced in 1.5.2, use `">= 1.5.2 < 2"`.
 
+### peerDependenciesMeta
+
+When a user installs your package, npm will emit warnings if packages specified in `peerDependencies` are not already installed. The `peerDependenciesMeta` field serves to provide npm more information on how your peer dependencies are to be used. Specifically, it allows peer dependencies to be marked as optional.
+
+For example:
+
+```json
+{
+  "name": "tea-latte",
+  "version": "1.3.5",
+  "peerDependencies": {
+    "tea": "2.x",
+    "soy-milk": "1.2"
+  },
+  "peerDependenciesMeta": {
+    "soy-milk": {
+      "optional": true
+    }
+  }
+}
+```
+
+Marking a peer dependency as optional ensures npm will not emit a warning if the `soy-milk` package is not installed on the host. This allows you to integrate and interact with a variety of host packages without requiring all of them to be installed.
+
 ### bundledDependencies
 
 This defines an array of package names that will be bundled when publishing