shx is a wrapper around ShellJS Unix
commands, providing an easy solution for simple Unix-like, cross-platform
commands in npm package scripts.
shx is proudly tested on every LTS node release since v18!
Difference Between ShellJS and shx
ShellJS: Good for writing long scripts, all in JS, running via NodeJS (e.g. node myScript.js).
shx: Good for writing one-off commands in npm package scripts (e.g. "clean": "shx rm -rf out/").
Install
npm install shx --save-dev
This will allow using shx in your package.json scripts.
Usage
Command Line
If you'd like to use shx on the command line, install it globally with the -g flag.
The following code can be run either a Unix or Windows command line:
$ shx pwd # ShellJS commands are supported automatically/home/username/path/to/dir$ shx ls # files are outputted one per linefile.txtfile2.txt$ shx rm *.txt # a cross-platform way to delete files!$ shx ls$ shx echo "Hi there!"Hi there!$ shx touch helloworld.txt$ shx cp helloworld.txt foobar.txt$ shx mkdir sub$ shx lsfoobar.txthelloworld.txtsub$ shx rm -r sub # options work as well$ shx --silent ls fakeFileName # silence error output$ shx --negate test -d dir # Negate status code output (e.g., failed commands will now have status 0)
All commands internally call the ShellJS corresponding function, guaranteeing
cross-platform compatibility.
package.json
ShellJS is good for writing long scripts. If you want to write bash-like,
platform-independent scripts, we recommend you go with that.
However, shx is ideal for one-liners inside package.json:
It's safe to use && and || operators in npm package scripts. These will be
interpreted by the operating system's shell (sh on Unix, cmd.exe on
Windows). If you're using glob operators like * or **, then we recommend to
put these in double quotes, which ensures that shx will expand the glob
rather than the operating system shell.
[!IMPORTANT]
Windows treats single quotes (ex. 'some string') differently than double
quotes.
We recommend
wrapping your arguments in escaped double quotes so that your code is
compatible cross platform (ex. "clean": "shx echo \"some string\"").
Command reference
Shx exposes most ShellJS
commands. If a command is
not listed here, assume it's supported!
sed
Shx provides unix-like syntax on top of shell.sed(). So ShellJS code like:
shx sed -i "s/original string/replacement/g" filename.txt
Note: like unix sed, shx sed treats / as a special character, and
this must be
escaped (as
\/ in the shell, or \\/ in package.json) if you intend to use this
character in either the regex or replacement string. Do not escape /
characters in the file path.
Unsupported Commands
As mentioned above, most ShellJS commands are supported in shx. Due to the
differences in execution environments between ShellJS and shx (JS vs CLI) the
following commands are not supported:
Unsupported command
Recommend workaround
shx cd
Just use plain old cd (it's the same on windows too)
shx pushd
Just use plain old pushd. Use forward slashes and double-quote the path. (e.g. pushd "../docs". This would fail on Windows without the quotes)
shx popd
Just use plain old popd
shx dirs
No workaround
shx set
See below
shx exit
Just use plain old exit
shx exec
Instead of shx exec cmd, just use plain old cmd
shx ShellString
No workaround (but why would you want this?)
Shx options
Shx allows you to modify its behavior by passing arguments. Here's a list of
supported options: