docs: document how to bundle yargs with webpack/ncc (yargs#1757)

README.md

@@ -162,6 +162,7 @@ Having problems? want to contribute? join our [community slack](http://devtoolsc
   * [Composing Your App Using Commands](/docs/advanced.md#commands)
   * [Building Configurable CLI Apps](/docs/advanced.md#configuration)
   * [Customizing Yargs' Parser](/docs/advanced.md#customizing)
+  * [Bundling yargs](/docs/bundling.md)
 * [Contributing](/contributing.md)
 
 ## Supported Node.js Versions

docs/api.md

@@ -7,7 +7,8 @@ This document is the Yargs API reference. There are more documentation files in
 - [Examples](https://github.com/yargs/yargs/blob/master/docs/examples.md)
 - [Advanced Topics](https://github.com/yargs/yargs/blob/master/docs/advanced.md)
 - [TypeScript usage examples](https://github.com/yargs/yargs/blob/master/docs/typescript.md)
-- [Webpack usage examples](https://github.com/yargs/yargs/blob/master/docs/webpack.md)
+- [Browser usage example](https://github.com/yargs/yargs/blob/master/docs/browser.md)
+- [Bundling](https://github.com/yargs/yargs/blob/master/docs/bundling.md)
 - [Parsing Tricks](https://github.com/yargs/yargs/blob/master/docs/tricks.md)
 
 API reference

docs/browser.md

@@ -24,9 +24,3 @@ the browser:
 
 A full example can be found in [example/yargs.html](/example/yargs.html), or
 on [jsfiddle](https://jsfiddle.net/bencoe/m9fv2oet/3/).
-
-## Bundling
-
-Even though yargs can run directly in the browser, you  will still likely 
-want to use a tool like [rollup.js](https://rollupjs.org/guide/en/) to create
-a bundle for the browser.

docs/bundling.md

@@ -0,0 +1,66 @@
+## Bundling yargs
+
+This document outlines how to bundle your libraries that use yargs into
+standalone distributions.
+
+### You might not need to bundle
+
+Newer releases of yargs can run directly in modern browsers, take a look at
+[Running yargs in the browser](https://github.com/yargs/yargs/blob/master/docs/browser.md).
+
+## ncc
+
+If you are targetting Node.js with your bundle, we recommend using
+[`@vercel/ncc`](https://www.npmjs.com/package/@vercel/ncc).
+
+Given a CommonJS file, **index.js**:
+
+```js
+const yargs = require('yargs')
+const chalk = require('chalk')
+yargs
+  .option('awesome-opt', {
+    describe: `my awesome ${chalk.green('option')}`
+  })
+  .parse()
+```
+
+You can simply run: `ncc build index.js`.
+
+### Webpack
+
+Given a CommonJS file, **index.js**:
+
+```js
+const yargs = require('yargs')
+const chalk = require('chalk')
+yargs
+  .option('awesome-opt', {
+    describe: `my awesome ${chalk.green('option')}`
+  })
+  .parse()
+```
+
+You can create a CommonJS bundle with the following `webpack.config.js`:
+
+```js
+module.exports = {
+  mode: "development",
+  entry: {
+    index: "./index.js",
+  },
+  output: {
+    filename: './index.js'
+  },
+  resolve: {
+    extensions: ['.js', '.cjs', '.json']
+  },
+  target: 'node',
+  devtool: "source-map-inline",
+  externals: {
+    'cliui': 'commonjs2 cliui',
+    'y18n': 'commonjs2 y18n',
+    'yargs-parser': 'commonjs2 yargs-parser',
+  },
+};
+```