shx

What is shx?

The shx npm package provides a way to use shell commands in a cross-platform manner. It allows you to run common shell commands like `cp`, `rm`, `mv`, `echo`, and more, directly from your Node.js scripts or npm scripts, ensuring compatibility across different operating systems.

What are shx's main functionalities?

Copy files

This command copies a file from `source.txt` to `destination.txt`. It works across different operating systems without needing to worry about platform-specific syntax.

shx cp source.txt destination.txt

Remove files or directories

This command removes a file or directory at the specified path. The `-rf` flags ensure that the removal is recursive and forces the deletion without prompting.

shx rm -rf path/to/directory

Move or rename files

This command moves or renames a file from `oldname.txt` to `newname.txt`. It provides a simple way to handle file renaming or moving operations.

shx mv oldname.txt newname.txt

Echo text

This command prints the text 'Hello, World!' to the console. It can be used to output messages or variables in scripts.

shx echo 'Hello, World!'

Create directories

This command creates a new directory at the specified path. The `-p` flag ensures that any necessary parent directories are also created.

shx mkdir -p path/to/new/directory

Other packages similar to shx

shelljs

ShellJS is a portable (Windows/Linux/macOS) implementation of Unix shell commands on top of the Node.js API. It provides a similar set of functionalities as shx, allowing you to run shell commands in a cross-platform way. However, ShellJS is more of a library that you can use within your Node.js scripts, whereas shx is designed to be used directly in npm scripts.

fs-extra

fs-extra is a package that extends the native Node.js `fs` module with additional methods like `copy`, `remove`, and `mkdirp`. While it doesn't provide a direct shell-like interface, it offers similar file system manipulation capabilities with a focus on ease of use and additional features.

rimraf

rimraf is a package specifically designed to delete files and directories, similar to the `rm -rf` command. It is highly reliable and handles various edge cases, making it a good alternative for file and directory removal tasks.

README

Shx

shx is a wrapper around ShellJS Unix commands, providing an easy solution for simple Unix-like, cross-platform commands in npm package scripts.

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 line
file.txt
file2.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 ls
foobar.txt
helloworld.txt
sub

$ shx rm -r sub                 # options work as well

$ shx --silent ls fakeFileName  # silence error output

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:

{
  "scripts": {
    "clean": "shx rm -rf build dist && shx echo Done"
  }
}

Unsupported Commands

Due to the differences in execution environments between ShellJS and shx (JS vs CLI) some 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:

set flag	shell.config setting	shx command	Effect
-e	config.fatal = true	Not supported	Exit upon first error
-v	config.verbose = true	shx --verbose cd foo	Log the command as it's run
-f	config.noglob = true	shx --noglob cat '*.txt'	Don't expand wildcards
N/A	config.silent = true	shx --silent cd noexist	Don't show error output

Team

Nate Fischer	Ari Porad	Levi Thomason

Changelog

v0.3.0 (2018-06-08)

Full Changelog

Closed issues:

• Ship shx with shelljs@v0.8 #125
• Support executables #124
• Discuss: popd/pushd workarounds #121
• Feature request: date #120
• Fails trying to utilise the new script-shell npm config #117
• Refactor: consider using process.exitCode #116
• Add node v8 to CI #114
• can we use this without the shx prefix? #113
• Command substitution feature #112

Merged pull requests:

• feat: bump shelljs to expose new features #126 (nfischer)
• fix: use process.exitCode to wait for streams #123 (nfischer)
• Add workaround for pushd and popd to README #122 (eteeselink)
• Add node 8 to CI #115 (freitagbr)