From b150eaeff428180bfa03be53fd741d5625897758 Mon Sep 17 00:00:00 2001
From: claudiahdz <cghr1990@gmail.com>
Date: Fri, 15 Nov 2019 19:16:23 +0200
Subject: [PATCH] docs: package aliases

PR-URL: https://github.com/npm/cli/pull/485
Credit: @claudiahdz
Close: #485
Reviewed-by: @claudiahdz
---
 docs/content/cli-commands/npm-install.md | 19 +++++++++++++++++++
 lib/install.js                           |  1 +
 2 files changed, 20 insertions(+)

diff --git a/docs/content/cli-commands/npm-install.md b/docs/content/cli-commands/npm-install.md
index cfb96aeedd939..8e661bf643f39 100644
--- a/docs/content/cli-commands/npm-install.md
+++ b/docs/content/cli-commands/npm-install.md
@@ -16,6 +16,7 @@ npm install [<@scope>/]<name>
 npm install [<@scope>/]<name>@<tag>
 npm install [<@scope>/]<name>@<version>
 npm install [<@scope>/]<name>@<version range>
+npm install <alias>@npm:<name>
 npm install <git-host>:<git-user>/<repo-name>
 npm install <git repo url>
 npm install <tarball file>
@@ -113,6 +114,24 @@ after packing it up into a tarball (b).
 
           npm install sax
 
+* `npm install <alias>@npm:<name>`:
+
+    Install a package under a custom alias. Allows multiple versions of
+    a same-name package side-by-side, more convenient import names for
+    packages with otherwise long ones and using git forks replacements
+    or forked npm packages as replacements. Aliasing works only on your
+    project and does not rename packages in transitive dependencies.
+    Aliases should follow the naming conventions stated in
+    [`validate-npm-package-name`](https://www.npmjs.com/package/validate-npm-package-name#naming-rules).
+
+    Examples:
+
+          npm install my-react@npm:react
+          npm install jquery2@npm:jquery@2
+          npm install jquery3@npm:jquery@3
+          npm install npa@npm:npm-package-arg
+
+
     `npm install` saves any specified packages into `dependencies` by default.
     Additionally, you can control where and how they get saved with some
     additional flags:
diff --git a/lib/install.js b/lib/install.js
index a4cf2b186de51..528a3a0b59a75 100644
--- a/lib/install.js
+++ b/lib/install.js
@@ -26,6 +26,7 @@ install.usage = usage(
   '\nnpm install [<@scope>/]<pkg>@<tag>' +
   '\nnpm install [<@scope>/]<pkg>@<version>' +
   '\nnpm install [<@scope>/]<pkg>@<version range>' +
+  '\nnpm install <alias>@npm:<name>' +
   '\nnpm install <folder>' +
   '\nnpm install <tarball file>' +
   '\nnpm install <tarball url>' +