doc: update documentation for bundledDependencies

1 files changed, 25 insertions, 1 deletions

diff --git a/doc/files/package.json.md b/doc/files/package.json.md
index 8c658200b..3c61d8b88 100644
--- a/doc/files/package.json.md
+++ b/doc/files/package.json.md
@@ -578,7 +578,31 @@ this. If you depend on features introduced in 1.5.2, use `">= 1.5.2 < 2"`.
 
 ## bundledDependencies
 
-Array of package names that will be bundled when publishing the package.
+This defines an array of package names that will be bundled when publishing
+the package.
+
+In cases where you need to preserve npm packages locally or have them
+available through a single file download, you can bundle the packages in a
+tarball file by specifying the package names in the `bundledDependencies`
+array and executing `npm pack`.
+
+For example:
+
+If we define a package.json like this:
+
+```
+{
+  "name": "awesome-web-framework",
+  "version": "1.0.0",
+  "bundledDependencies": [
+    'renderized', 'super-streams'
+  ]
+}
+```
+we can obtain `awesome-web-framework-1.0.0.tgz` file by running `npm pack`.
+This file contains the dependencies `renderized` and `super-streams` which
+can be installed in a new project by executing `npm install
+awesome-web-framework-1.0.0.tgz`.
 
 If this is spelled `"bundleDependencies"`, then that is also honored.