Skip to content

Commit f145401

Browse files
feat: add shell completions (#4840)
* feat: add tab completions * fix(complete): resolve command aliases and make the parser optional Completing after an alias returned only the global options, because `@bomb.sh/tab` registers each command under `command.name()` and has no alias concept: `webpack b <TAB>` offered 4 candidates where `webpack build <TAB>` offers 25, and `webpack s <TAB>` 4 against `serve`'s 98. The alias being completed is now registered against the command it stands for, so every alias resolves. Only the requested one is registered, which keeps `webpack <TAB>` listing the eight commands rather than all thirteen names. Global options are registered on the root command, so nothing offered them after a command, though they are accepted there: `webpack build --col` did not complete `--color`, and `configtest`, `help` and `complete` offered nothing at all, having no options of their own. Every command now carries them. `@bomb.sh/tab` also moves to an optional peer dependency, next to the other packages the CLI loads on demand. It is imported only to serve a completion request, so installing it is the user's choice: the shell runs `complete -- <words>` on every keypress and now gets silence when the package is absent, while `complete <shell>` says what to install. Also updates the dev-server 6 help snapshots, which were added after this work branched. Co-authored-by: AmirSa12 <[email protected]> * fix(complete): keep a partial command expanding to its full name Registering the requested alias made it a suggestion of its own, so `webpack b<TAB>` offered `build` and `b` and the shell, having two candidates, left the word at their common prefix instead of writing `build` out. The last word is the one being typed, so only the words before it name the command an alias has to resolve. Co-authored-by: AmirSa12 <[email protected]> * test(complete): cover the option-value handlers Patch coverage reported 30 uncovered lines, most of them handler bodies that only run while the option they belong to is being completed. Covers `build --progress`, `version --output`, the root `--help`, and the shell argument of `complete` itself. Co-authored-by: AmirSa12 <[email protected]> * test(complete): cover the missing-parser paths `@bomb.sh/tab` is optional, so the two paths that run without it carry the behaviour a user without it sees, and both were checked by hand only. A resolve hook now hides the package the way an install that never had it does, pinning that a completion request prints nothing on either stream and that asking for a script reports what to install. * docs: describe shell completion Covers what completes, that `@bomb.sh/tab` has to be installed for it, and the line to add per shell. Also lists `complete` among the commands in both readmes, the second of which quotes `--help` and so has to match it. Co-authored-by: AmirSa12 <[email protected]> --------- Co-authored-by: AmirSa12 <[email protected]>
1 parent 7d40e4e commit f145401

12 files changed

Lines changed: 535 additions & 8 deletions

‎.changeset/tab-completions.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"webpack-cli": minor
3+
---
4+
5+
feat: add shell completions for zsh, bash, fish and powershell through the `complete` command

‎.cspell.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,8 @@
106106
"Zenitsu",
107107
"quickstart",
108108
"pinia",
109-
"watchpack"
109+
"watchpack",
110+
"zsh"
110111
],
111112
"dictionaries": ["npm", "software-terms"],
112113
"ignorePaths": [

‎README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
- [Packages](#packages)
2727
- [Commands](#commands)
2828
- [Getting started](#getting-started)
29+
- [Shell completion](#shell-completion)
2930
- [Exit codes and their meanings](#exit-codes-and-their-meanings)
3031
- [Contributing and Internal Documentation](#contributing-and-internal-documentation)
3132
- [Funding](#funding)
@@ -58,6 +59,7 @@ Supporting developers is an important task for webpack CLI.
5859
Thus, webpack CLI provides different commands for many common tasks.
5960

6061
- [`build|bundle|b [entries...] [options]`](https://webpack.js.org/api/cli/#build) - Run webpack (default command, can be omitted).
62+
- `complete [shell]` - Print a shell completion script, see [Shell completion](#shell-completion).
6163
- [`configtest|t [config-path]`](https://webpack.js.org/api/cli/#configtest) - Validate a webpack configuration.
6264
- [`help|h [command] [option]`](https://webpack.js.org/api/cli/#help) - Display help for commands and options.
6365
- [`info|i [options]`](https://webpack.js.org/api/cli/#info) - Returns information related to the local environment.
@@ -79,6 +81,41 @@ npx create-webpack-app init
7981

8082
You will then be prompted for some questions about which features you want to use, such as `scss`, `typescript`, `PWA` support or other features.
8183

84+
## Shell completion
85+
86+
Commands, their options and the values those options accept can be completed in `zsh`, `bash`, `fish` and `powershell`. The completions are read from webpack's own schema, so they cover whatever your webpack and `webpack-dev-server` versions support.
87+
88+
Completion is served by [`@bomb.sh/tab`](https://www.npmjs.com/package/@bomb.sh/tab), which is optional and not installed with `webpack-cli`:
89+
90+
```sh
91+
npm install --save-dev @bomb.sh/tab
92+
```
93+
94+
Then load the script for your shell:
95+
96+
```sh
97+
# zsh
98+
echo 'source <(webpack complete zsh)' >> ~/.zshrc
99+
100+
# bash
101+
echo 'source <(webpack complete bash)' >> ~/.bashrc
102+
103+
# fish
104+
webpack complete fish > ~/.config/fish/completions/webpack.fish
105+
106+
# powershell
107+
webpack complete powershell > ~/.webpack-completion.ps1
108+
echo '. ~/.webpack-completion.ps1' >> $PROFILE
109+
```
110+
111+
Once the shell is restarted, `Tab` completes commands, their aliases, options and option values:
112+
113+
```sh
114+
webpack b<Tab> # webpack build
115+
webpack build --mode=<Tab> # development, production, none
116+
webpack serve --his<Tab> # webpack serve --history-api-fallback
117+
```
118+
82119
## Exit codes and their meanings
83120

84121
| Exit Code | Description |

‎package-lock.json‎

Lines changed: 33 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@
4848
"prepare": "husky"
4949
},
5050
"devDependencies": {
51+
"@bomb.sh/tab": "^0.0.22",
5152
"@babel/core": "^8.0.1",
5253
"@babel/preset-env": "^8.0.2",
5354
"@babel/register": "^8.0.1",

‎packages/webpack-cli/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ npx webpack-cli --help verbose
6464

6565
```
6666
build|bundle|b [entries...] [options] Run webpack (default command, can be omitted).
67+
complete [shell] Generate shell completion scripts.
6768
configtest|t [config-path] Validate a webpack configuration.
6869
help|h [command] [option] Display help for commands and options.
6970
info|i [options] Outputs information about your system.

‎packages/webpack-cli/package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@
4444
"@types/envinfo": "^7.8.4"
4545
},
4646
"peerDependencies": {
47+
"@bomb.sh/tab": "^0.0.22",
4748
"js-yaml": "^4.0.0 || ^5.0.0",
4849
"json5": "^2.2.3",
4950
"toml": "^3.0.0 || ^4.0.0 || ^5.0.0",
@@ -52,6 +53,9 @@
5253
"webpack-dev-server": "^5.0.0 || ^6.0.0"
5354
},
5455
"peerDependenciesMeta": {
56+
"@bomb.sh/tab": {
57+
"optional": true
58+
},
5559
"js-yaml": {
5660
"optional": true
5761
},

0 commit comments

Comments
 (0)