diff --git a/docs/content/commands/npm-ci.md b/docs/content/commands/npm-ci.md
index 97d1aa5523dd7..b4ce811869bb2 100644
--- a/docs/content/commands/npm-ci.md
+++ b/docs/content/commands/npm-ci.md
@@ -46,6 +46,13 @@ In short, the main differences between using `npm install` and `npm ci` are:
 * It will never write to `package.json` or any of the package-locks:
   installs are essentially frozen.
 
+NOTE: If you create your `package-lock.json` file by running `npm install`
+with flags that can affect the shape of your dependency tree, such as
+`--legacy-peer-deps`, you _must_ provide the same flags to `npm ci` or you
+are likely to encounter errors. An easy way to do this is to run
+`npm config set legacy-peer-deps=true --location=project` and commit the
+`.npmrc` file to your repo.
+
 ### Example
 
 Make sure you have a package-lock and an up-to-date install: