diff --git a/.editorconfig b/.editorconfig
deleted file mode 100644
index 3fd345c8a..000000000
--- a/.editorconfig
+++ /dev/null
@@ -1,14 +0,0 @@
-root = true
-
-[*]
-
-indent_style = space
-indent_size = 2
-
-end_of_line = lf
-charset = utf-8
-trim_trailing_whitespace = true
-insert_final_newline = true
-
-[*.md]
-trim_trailing_whitespace = false
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index ab1bd7c89..d13e37711 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -16,7 +16,7 @@ jobs:
with:
node-version: ${{ matrix.node }}
- run: node --version
- - run: npm install
+ - run: npm install --engine-strict
- run: npm test
windows:
runs-on: windows-latest
@@ -27,6 +27,34 @@ jobs:
node-version: 12
- run: npm install
- run: npm test
+ esm:
+ runs-on: ubuntu-latest
+ strategy:
+ matrix:
+ node: [14]
+ steps:
+ - uses: actions/checkout@v1
+ - uses: actions/setup-node@v1
+ with:
+ node-version: ${{ matrix.node }}
+ - run: node --version
+ - run: npm install --engine-strict
+ - run: npm run test:esm
+ deno:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v2
+ - uses: actions/setup-node@v1
+ with:
+ node-version: 14
+ - run: npm install
+ - run: npm run compile
+ - uses: denolib/setup-deno@v2
+ with:
+ deno-version: v1.x
+ - run: |
+ deno --version
+ deno test --allow-read test/deno/*
coverage:
runs-on: ubuntu-latest
steps:
diff --git a/.gitignore b/.gitignore
index 624a7ce7d..2cfab6bc8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,4 +6,6 @@ node_modules/
test.js
coverage
package-lock.json
+example.*
+.DS_Store
.npmrc
diff --git a/.mocharc.json b/.mocharc.json
deleted file mode 100644
index ef1c3645a..000000000
--- a/.mocharc.json
+++ /dev/null
@@ -1,6 +0,0 @@
-{
- "spec": [
- "build/test",
- "test"
- ]
-}
diff --git a/.versionrc b/.versionrc
deleted file mode 100644
index 0b7f5a6c8..000000000
--- a/.versionrc
+++ /dev/null
@@ -1,9 +0,0 @@
-{
- "types": [
- {"type":"feat","section":"Features"},
- {"type":"fix","section":"Bug Fixes"},
- {"type":"test","section":"Tests", "hidden": true},
- {"type":"build","section":"Build System", "hidden": true},
- {"type":"ci","hidden":true}
- ]
-}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a010cf34f..33336f5b8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -296,125 +296,3 @@ arguments when duplicates are provided
* dropping Node 6 which hits end of life in April 2019
* see [yargs-parser@12.0.0 CHANGELOG](https://github.com/yargs/yargs-parser/blob/master/CHANGELOG.md#breaking-changes)
* we now warn if the yargs stanza package.json is used.
-
-
-
-
-## [12.0.5](https://github.com/yargs/yargs/compare/v12.0.4...v12.0.5) (2018-11-19)
-
-
-### Bug Fixes
-
-* allows camel-case, variadic arguments, and strict mode to be combined ([#1247](https://github.com/yargs/yargs/issues/1247)) ([eacc035](https://github.com/yargs/yargs/commit/eacc035))
-
-
-
-
-## [12.0.4](https://github.com/yargs/yargs/compare/v12.0.3...v12.0.4) (2018-11-10)
-
-
-### Bug Fixes
-
-* don't load config when processing positionals ([5d0dc92](https://github.com/yargs/yargs/commit/5d0dc92))
-
-
-
-
-## [12.0.3](https://github.com/yargs/yargs/compare/v12.0.2...v12.0.3) (2018-10-06)
-
-
-### Bug Fixes
-
-* $0 contains first arg in bundled electron apps ([#1206](https://github.com/yargs/yargs/issues/1206)) ([567820b](https://github.com/yargs/yargs/commit/567820b))
-* accept single function for middleware ([66fd6f7](https://github.com/yargs/yargs/commit/66fd6f7)), closes [#1214](https://github.com/yargs/yargs/issues/1214) [#1214](https://github.com/yargs/yargs/issues/1214)
-* hide `hidden` options from help output even if they are in a group ([#1221](https://github.com/yargs/yargs/issues/1221)) ([da54028](https://github.com/yargs/yargs/commit/da54028))
-* improve Norwegian Bokmål translations ([#1208](https://github.com/yargs/yargs/issues/1208)) ([a458fa4](https://github.com/yargs/yargs/commit/a458fa4))
-* improve Norwegian Nynorsk translations ([#1207](https://github.com/yargs/yargs/issues/1207)) ([d422eb5](https://github.com/yargs/yargs/commit/d422eb5))
-
-
-
-
-## [12.0.2](https://github.com/yargs/yargs/compare/v12.0.1...v12.0.2) (2018-09-04)
-
-
-### Bug Fixes
-
-* middleware should work regardless of when method is called ([664b265](https://github.com/yargs/yargs/commit/664b265)), closes [#1178](https://github.com/yargs/yargs/issues/1178)
-* translation not working when using __ with a single parameter ([#1183](https://github.com/yargs/yargs/issues/1183)) ([f449aea](https://github.com/yargs/yargs/commit/f449aea))
-* upgrade os-locale to version that addresses license issue ([#1195](https://github.com/yargs/yargs/issues/1195)) ([efc0970](https://github.com/yargs/yargs/commit/efc0970))
-
-
-
-
-## [12.0.1](https://github.com/yargs/yargs/compare/v12.0.0...v12.0.1) (2018-06-29)
-
-
-
-
-# [12.0.0](https://github.com/yargs/yargs/compare/v11.1.0...v12.0.0) (2018-06-26)
-
-
-### Bug Fixes
-
-* .argv and .parse() now invoke identical code path ([#1126](https://github.com/yargs/yargs/issues/1126)) ([f13ebf4](https://github.com/yargs/yargs/commit/f13ebf4))
-* remove the trailing white spaces from the help output ([#1090](https://github.com/yargs/yargs/issues/1090)) ([3f0746c](https://github.com/yargs/yargs/commit/3f0746c))
-* **completion:** Avoid default command and recommendations during completion ([#1123](https://github.com/yargs/yargs/issues/1123)) ([036e7c5](https://github.com/yargs/yargs/commit/036e7c5))
-
-
-### Chores
-
-* test Node.js 6, 8 and 10 ([#1160](https://github.com/yargs/yargs/issues/1160)) ([84f9d2b](https://github.com/yargs/yargs/commit/84f9d2b))
-* upgrade to version of yargs-parser that does not populate value for unset boolean ([#1104](https://github.com/yargs/yargs/issues/1104)) ([d4705f4](https://github.com/yargs/yargs/commit/d4705f4))
-
-
-### Features
-
-* add support for global middleware, useful for shared tasks like metrics ([#1119](https://github.com/yargs/yargs/issues/1119)) ([9d71ac7](https://github.com/yargs/yargs/commit/9d71ac7))
-* allow setting scriptName $0 ([#1143](https://github.com/yargs/yargs/issues/1143)) ([a2f2eae](https://github.com/yargs/yargs/commit/a2f2eae))
-* remove `setPlaceholderKeys` ([#1105](https://github.com/yargs/yargs/issues/1105)) ([6ee2c82](https://github.com/yargs/yargs/commit/6ee2c82))
-
-
-### BREAKING CHANGES
-
-* Options absent from `argv` (not set via CLI argument) are now absent from the parsed result object rather than being set with `undefined`
-* drop Node 4 from testing matrix, such that we'll gradually start drifting away from supporting Node 4.
-* yargs-parser does not populate 'false' when boolean flag is not passed
-* tests that assert against help output will need to be updated
-
-
-
-
-# [11.1.0](https://github.com/yargs/yargs/compare/v11.0.0...v11.1.0) (2018-03-04)
-
-
-### Bug Fixes
-
-* choose correct config directory when require.main does not exist ([#1056](https://github.com/yargs/yargs/issues/1056)) ([a04678c](https://github.com/yargs/yargs/commit/a04678c))
-
-
-### Features
-
-* allow hidden options to be displayed with --show-hidden ([#1061](https://github.com/yargs/yargs/issues/1061)) ([ea862ae](https://github.com/yargs/yargs/commit/ea862ae))
-* extend *.rc files in addition to json ([#1080](https://github.com/yargs/yargs/issues/1080)) ([11691a6](https://github.com/yargs/yargs/commit/11691a6))
-
-
-
-
-# [11.0.0](https://github.com/yargs/yargs/compare/v10.1.2...v11.0.0) (2018-01-22)
-
-
-### Bug Fixes
-
-* Set implicit nargs=1 when type=number requiresArg=true ([#1050](https://github.com/yargs/yargs/issues/1050)) ([2b56812](https://github.com/yargs/yargs/commit/2b56812))
-
-
-### Features
-
-* requiresArg is now simply an alias for nargs(1) ([#1054](https://github.com/yargs/yargs/issues/1054)) ([a3ddacc](https://github.com/yargs/yargs/commit/a3ddacc))
-
-
-### BREAKING CHANGES
-
-* requiresArg now has significantly different error output, matching nargs.
-
-[Historical Versions](/docs/CHANGELOG-historical.md)
diff --git a/README.md b/README.md
index f73236d0c..0457fc4dc 100644
--- a/README.md
+++ b/README.md
@@ -8,14 +8,14 @@
-[![Build Status][travis-image]][travis-url]
+![ci](https://github.com/yargs/yargs/workflows/ci/badge.svg)
[![NPM version][npm-image]][npm-url]
[![js-standard-style][standard-image]][standard-url]
[![Coverage][coverage-image]][coverage-url]
[![Conventional Commits][conventional-commits-image]][conventional-commits-url]
[![Slack][slack-image]][slack-url]
-## Description :
+## Description
Yargs helps you build interactive command line tools, by parsing arguments and generating an elegant user interface.
It gives you:
@@ -40,7 +40,7 @@ Bleeding edge version with the most recent features:
npm i yargs@next
```
-## Usage :
+## Usage
### Simple Example
@@ -88,7 +88,9 @@ require('yargs') // eslint-disable-line
Run the example above with `--help` to see the help for the application.
-## TypeScript
+## Supported Platforms
+
+### TypeScript
yargs has type definitions at [@types/yargs][type-definitions].
@@ -98,15 +100,50 @@ npm i @types/yargs --save-dev
See usage examples in [docs](/docs/typescript.md).
-## Webpack
+### Deno
+
+As of `v16`, `yargs` supports [Deno](https://github.com/denoland/deno):
+
+```typescript
+import { Yargs, YargsType, Arguments } from 'https://deno.land/x/yargs/deno.ts'
+
+Yargs()
+ .command('download ', 'download a list of files', (yargs: YargsType) => {
+ return yargs.positional('files', {
+ describe: 'a list of files to do something with'
+ })
+ }, (argv: Arguments) => {
+ console.info(argv)
+ })
+ .strictCommands()
+ .demandCommand(1)
+ .parse(Deno.args)
+```
+
+### ESM
+
+As of `v16`,`yargs` supports ESM imports:
+
+```js
+import { Yargs, getProcessArgvWithoutBin } from 'yargs'
+
+Yargs(getProcessArgvWithoutBin())
+ .command('curl ', 'fetch the contents of the URL', () => {}, (argv) => {
+ console.info(argv)
+ })
+ .demandCommand(1)
+ .argv
+```
+
+### Usage in Browser
-See usage examples of yargs with webpack in [docs](/docs/webpack.md).
+See examples of using yargs in the browser in [docs](/docs/browser.md).
-## Community :
+## Community
Having problems? want to contribute? join our [community slack](http://devtoolscommunity.herokuapp.com).
-## Documentation :
+## Documentation
### Table of Contents
@@ -131,8 +168,6 @@ Libraries in this ecosystem make a best effort to track
[Node.js' release schedule](https://nodejs.org/en/about/releases/). Here's [a
post on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a).
-[travis-url]: https://travis-ci.org/yargs/yargs
-[travis-image]: https://img.shields.io/travis/yargs/yargs/master.svg
[npm-url]: https://www.npmjs.com/package/yargs
[npm-image]: https://img.shields.io/npm/v/yargs.svg
[standard-image]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg
diff --git a/browser.mjs b/browser.mjs
new file mode 100644
index 000000000..f3d32f2b2
--- /dev/null
+++ b/browser.mjs
@@ -0,0 +1,7 @@
+// Bootstrap yargs for browser:
+import browserPlatformShim from './lib/platform-shims/browser.mjs'
+import { YargsWithShim } from './build/lib/yargs-factory.js'
+
+const Yargs = YargsWithShim(browserPlatformShim)
+
+export { Yargs }
diff --git a/deno.ts b/deno.ts
new file mode 100644
index 000000000..d985e1cd1
--- /dev/null
+++ b/deno.ts
@@ -0,0 +1,16 @@
+// Bootstrap yargs for Deno platform:
+import denoPlatformShim from './lib/platform-shims/deno.ts'
+import { YargsWithShim } from './build/lib/yargs-factory.js'
+import { YargsInstance as YargsType, Arguments } from './build/lib/yargs-factory.d.ts'
+
+const WrappedYargs = YargsWithShim(denoPlatformShim)
+
+function Yargs (args?: string[]): YargsType {
+ return WrappedYargs(args)
+}
+
+export {
+ Arguments,
+ Yargs,
+ YargsType
+}
diff --git a/docs/CHANGELOG-historical.md b/docs/CHANGELOG-historical.md
index ded558e3e..1bfaf1b4f 100644
--- a/docs/CHANGELOG-historical.md
+++ b/docs/CHANGELOG-historical.md
@@ -1,3 +1,123 @@
+
+## [12.0.5](https://github.com/yargs/yargs/compare/v12.0.4...v12.0.5) (2018-11-19)
+
+
+### Bug Fixes
+
+* allows camel-case, variadic arguments, and strict mode to be combined ([#1247](https://github.com/yargs/yargs/issues/1247)) ([eacc035](https://github.com/yargs/yargs/commit/eacc035))
+
+
+
+
+## [12.0.4](https://github.com/yargs/yargs/compare/v12.0.3...v12.0.4) (2018-11-10)
+
+
+### Bug Fixes
+
+* don't load config when processing positionals ([5d0dc92](https://github.com/yargs/yargs/commit/5d0dc92))
+
+
+
+
+## [12.0.3](https://github.com/yargs/yargs/compare/v12.0.2...v12.0.3) (2018-10-06)
+
+
+### Bug Fixes
+
+* $0 contains first arg in bundled electron apps ([#1206](https://github.com/yargs/yargs/issues/1206)) ([567820b](https://github.com/yargs/yargs/commit/567820b))
+* accept single function for middleware ([66fd6f7](https://github.com/yargs/yargs/commit/66fd6f7)), closes [#1214](https://github.com/yargs/yargs/issues/1214) [#1214](https://github.com/yargs/yargs/issues/1214)
+* hide `hidden` options from help output even if they are in a group ([#1221](https://github.com/yargs/yargs/issues/1221)) ([da54028](https://github.com/yargs/yargs/commit/da54028))
+* improve Norwegian Bokmål translations ([#1208](https://github.com/yargs/yargs/issues/1208)) ([a458fa4](https://github.com/yargs/yargs/commit/a458fa4))
+* improve Norwegian Nynorsk translations ([#1207](https://github.com/yargs/yargs/issues/1207)) ([d422eb5](https://github.com/yargs/yargs/commit/d422eb5))
+
+
+
+
+## [12.0.2](https://github.com/yargs/yargs/compare/v12.0.1...v12.0.2) (2018-09-04)
+
+
+### Bug Fixes
+
+* middleware should work regardless of when method is called ([664b265](https://github.com/yargs/yargs/commit/664b265)), closes [#1178](https://github.com/yargs/yargs/issues/1178)
+* translation not working when using __ with a single parameter ([#1183](https://github.com/yargs/yargs/issues/1183)) ([f449aea](https://github.com/yargs/yargs/commit/f449aea))
+* upgrade os-locale to version that addresses license issue ([#1195](https://github.com/yargs/yargs/issues/1195)) ([efc0970](https://github.com/yargs/yargs/commit/efc0970))
+
+
+
+
+## [12.0.1](https://github.com/yargs/yargs/compare/v12.0.0...v12.0.1) (2018-06-29)
+
+
+
+
+# [12.0.0](https://github.com/yargs/yargs/compare/v11.1.0...v12.0.0) (2018-06-26)
+
+
+### Bug Fixes
+
+* .argv and .parse() now invoke identical code path ([#1126](https://github.com/yargs/yargs/issues/1126)) ([f13ebf4](https://github.com/yargs/yargs/commit/f13ebf4))
+* remove the trailing white spaces from the help output ([#1090](https://github.com/yargs/yargs/issues/1090)) ([3f0746c](https://github.com/yargs/yargs/commit/3f0746c))
+* **completion:** Avoid default command and recommendations during completion ([#1123](https://github.com/yargs/yargs/issues/1123)) ([036e7c5](https://github.com/yargs/yargs/commit/036e7c5))
+
+
+### Chores
+
+* test Node.js 6, 8 and 10 ([#1160](https://github.com/yargs/yargs/issues/1160)) ([84f9d2b](https://github.com/yargs/yargs/commit/84f9d2b))
+* upgrade to version of yargs-parser that does not populate value for unset boolean ([#1104](https://github.com/yargs/yargs/issues/1104)) ([d4705f4](https://github.com/yargs/yargs/commit/d4705f4))
+
+
+### Features
+
+* add support for global middleware, useful for shared tasks like metrics ([#1119](https://github.com/yargs/yargs/issues/1119)) ([9d71ac7](https://github.com/yargs/yargs/commit/9d71ac7))
+* allow setting scriptName $0 ([#1143](https://github.com/yargs/yargs/issues/1143)) ([a2f2eae](https://github.com/yargs/yargs/commit/a2f2eae))
+* remove `setPlaceholderKeys` ([#1105](https://github.com/yargs/yargs/issues/1105)) ([6ee2c82](https://github.com/yargs/yargs/commit/6ee2c82))
+
+
+### BREAKING CHANGES
+
+* Options absent from `argv` (not set via CLI argument) are now absent from the parsed result object rather than being set with `undefined`
+* drop Node 4 from testing matrix, such that we'll gradually start drifting away from supporting Node 4.
+* yargs-parser does not populate 'false' when boolean flag is not passed
+* tests that assert against help output will need to be updated
+
+
+
+
+# [11.1.0](https://github.com/yargs/yargs/compare/v11.0.0...v11.1.0) (2018-03-04)
+
+
+### Bug Fixes
+
+* choose correct config directory when require.main does not exist ([#1056](https://github.com/yargs/yargs/issues/1056)) ([a04678c](https://github.com/yargs/yargs/commit/a04678c))
+
+
+### Features
+
+* allow hidden options to be displayed with --show-hidden ([#1061](https://github.com/yargs/yargs/issues/1061)) ([ea862ae](https://github.com/yargs/yargs/commit/ea862ae))
+* extend *.rc files in addition to json ([#1080](https://github.com/yargs/yargs/issues/1080)) ([11691a6](https://github.com/yargs/yargs/commit/11691a6))
+
+
+
+
+# [11.0.0](https://github.com/yargs/yargs/compare/v10.1.2...v11.0.0) (2018-01-22)
+
+
+### Bug Fixes
+
+* Set implicit nargs=1 when type=number requiresArg=true ([#1050](https://github.com/yargs/yargs/issues/1050)) ([2b56812](https://github.com/yargs/yargs/commit/2b56812))
+
+
+### Features
+
+* requiresArg is now simply an alias for nargs(1) ([#1054](https://github.com/yargs/yargs/issues/1054)) ([a3ddacc](https://github.com/yargs/yargs/commit/a3ddacc))
+
+
+### BREAKING CHANGES
+
+* requiresArg now has significantly different error output, matching nargs.
+
+[Historical Versions](/docs/CHANGELOG-historical.md)
+
## [10.1.2](https://github.com/yargs/yargs/compare/v10.1.1...v10.1.2) (2018-01-17)
diff --git a/docs/browser.md b/docs/browser.md
new file mode 100644
index 000000000..c47b4ccd1
--- /dev/null
+++ b/docs/browser.md
@@ -0,0 +1,32 @@
+# Running yargs in the browser
+
+Newer versions of yargs have a `./browser.mjs` entrypoint, which can be used
+through a CDN like [unpkg.com](https://unpkg.com/) to load yargs directly in
+the browser:
+
+```html
+
+```
+
+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.
diff --git a/docs/webpack.md b/docs/webpack.md
deleted file mode 100644
index 012a846e0..000000000
--- a/docs/webpack.md
+++ /dev/null
@@ -1,103 +0,0 @@
-# Webpack usage examples
-
-## Install dependencies
-
-```bash
-$ npm install --save-dev webpack webpack-cli yargs
-```
-
-Additional dependencies for typescript users:
-
-```bash
-$ npm install --save-dev ts-loader typescript @types/yargs
-```
-
-## Sample program
-
-Create `src/index.js`:
-```js
-const yargs = require('yargs')
-
-console.log(yargs.parse())
-```
-
-Or for typescript users, `src/index.ts`:
-```ts
-import yargs = require('yargs');
-
-console.log(yargs.parse());
-```
-
-along with its `tsconfig.json`:
-```json
-{
- "compilerOptions": {
- "sourceMap": true
- }
-}
-```
-
-## Webpack configuration
-
-Create `webpack.config.js`:
-```js
-const path = require('path');
-
-module.exports = {
- entry: './src/index.js',
- output: {
- path: path.resolve(__dirname, 'dist'),
- filename: 'index.js'
- },
- stats: {
- // Ignore warnings due to yarg's dynamic module loading
- warningsFilter: [/node_modules\/yargs/]
- },
- target: 'node'
-}
-```
-
-For typescript users, replace :
-
-```js
-module.exports = {
- entry: './src/index.js',
- ...
-}
-```
-
-by:
-
-```js
-module.exports = {
- entry: './src/index.ts',
- module: {
- rules: [
- {
- test: /\.ts$/,
- use: [
- 'ts-loader',
- ]
- }
- ]
- },
- resolve: {
- extensions: ['.ts', '.js'],
- },
- ...
-}
-```
-
-## Build
-
-```bash
-$ ./node_modules/.bin/webpack --mode=production
-```
-
-## Run
-
-```bash
-$ rm -rf node_modules
-$ node dist/index.js
-{ _: [], '$0': 'dist/index.js' }
-```
diff --git a/example/yargs.html b/example/yargs.html
new file mode 100644
index 000000000..2d6f6d3b5
--- /dev/null
+++ b/example/yargs.html
@@ -0,0 +1,50 @@
+
+
+
+
+
+
+
+