shx

library0.4.2jsnpmunverified

shx is a command-line wrapper for ShellJS, designed specifically for providing cross-platform Unix-like commands within npm package scripts. It enables developers to use common shell commands such as `rm`, `cp`, `ls`, `mkdir`, `echo`, and `sed` consistently across different operating systems (Unix, Windows) without encountering shell-specific syntax issues. The current stable version, 0.4.0, is based on ShellJS v0.9, and mandates Node.js v18 or newer. Its primary differentiator from ShellJS (which is suitable for longer, programmatic JavaScript scripts) is its focus on simple, one-off command executions in `package.json` scripts, offering portability and ease of integration into build tooling and development workflows. shx's release cadence is tied to its upstream ShellJS dependency. It ensures a consistent CLI experience for basic file system operations.

devops web-framework data

npm install shx

github ↗package ↗

INSTALL

IMPORT

SIG · SHX

shx

devopsjavascriptv0.4.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

shx <command>

✓ shx rm -rf build/

✗ import shx from 'shx'; shx.rm('-rf', 'build/');

shx is a CLI tool, primarily used within `package.json` scripts or as a globally installed command-line utility. It is not designed for programmatic import into JavaScript or TypeScript files.

shx with arguments

✓ "clean": "shx rm -rf \"build/**/*.js\""

✗ "clean": "shx rm -rf 'build/**/*.js'"

For cross-platform compatibility, especially on Windows, always wrap arguments containing spaces, globs (`*`, `**`), or special characters in escaped double quotes (`\"argument\"`) within `package.json` scripts. Single quotes behave differently across shells.

shx command chaining

✓ "build-and-clean": "shx mkdir dist && shx cp src/*.js dist/ && shx echo 'Build complete.'"

✗ "build-and-clean": "shx mkdir dist; shx cp src/*.js dist/; shx echo 'Build complete.'"

Use `&&` for chaining commands in `package.json` scripts. This ensures that commands execute sequentially and subsequent commands only run if the previous one succeeded, which is consistent across operating system shells.

This `package.json` example demonstrates how to use `shx` for common build script tasks like cleaning directories, copying files, and creating directories, ensuring cross-platform compatibility.

{ "name": "my-project", "version": "1.0.0", "scripts": { "clean": "shx rm -rf dist/", "lint": "shx ls src/**/*.js | xargs eslint", "build": "shx mkdir -p dist/ && shx cp src/*.js dist/ && shx echo 'Build artifacts moved to dist/'", "postinstall": "shx echo 'shx commands are ready!'" }, "devDependencies": { "shx": "^0.4.0", "eslint": "^8.0.0" } }

shx --version

Debug

Known issues

breakingThe minimum Node.js version requirement has been bumped to `>= v18` in shx v0.4.0, aligning with ShellJS v0.9. Older Node.js versions are no longer supported.

fix

Upgrade your Node.js environment to version 18 or higher.

affects: >=0.4.0

breakingThe behavior of `shx sed -i` changed in v0.4.0. When using the `-i` (in-place) flag, `shx sed` will no longer print output to stdout, which is consistent with Unix `sed`. Using `shx sed` without `-i` will still print to stdout.

fix

Adjust scripts relying on stdout from `shx sed -i` to capture or process the modified file directly, rather than its output.

affects: >=0.4.0

gotchaWhen using glob operators (`*`, `**`) in `package.json` scripts, they must be enclosed in double quotes (e.g., `"src/**/*.js"`). This ensures `shx` performs the glob expansion, preventing the operating system's shell from misinterpreting or failing to expand them, especially on Windows.

fix

Always quote glob patterns within `shx` commands in `package.json` scripts, preferably with escaped double quotes like `\"pattern\"`.

affects: >=0.1.0

gotchaWindows shells (like `cmd.exe`) handle single quotes differently from Unix-like shells. To maintain cross-platform compatibility for arguments with spaces or special characters, it's recommended to wrap them in escaped double quotes (`\"some argument\"`) within your `package.json` scripts.

fix

Use escaped double quotes for all arguments passed to `shx` commands, e.g., `shx echo \"Hello World!\"`.

affects: >=0.1.0

gotchaWhen using `shx sed`, the `/` character in regular expressions or replacement strings must be escaped (as `\/` in the shell or `\\/` in `package.json` scripts) if it's not the delimiter. Unescaped `/` can lead to syntax errors.

fix

Escape forward slashes within `sed` patterns or replacement strings (e.g., `shx sed -i "s/original\/path/replacement\/path/g" file.txt`).

affects: >=0.1.0

Errors

Common errors & fixes

shx: command not found

The `shx` package is not installed or is not accessible in the system's PATH, or you're trying to run it outside of `npm` scripts without a global install.

fix

Install `shx` as a development dependency (`npm install shx --save-dev`) if used in `package.json` scripts, or globally (`npm install -g shx`) if intended for direct command-line use.

sed: -e expression #1, char X: unknown option to `s'

A special character, typically a forward slash (`/`), within the `sed` regular expression or replacement string was not properly escaped, leading to misinterpretation of the `s///` pattern.

fix

Ensure all forward slashes in the regex or replacement string (that are not pattern delimiters) are escaped with a backslash. For `package.json` scripts, this often means `\\/`.

The system cannot find the file specified.

Often occurs on Windows when glob patterns (like `*.js`) are not quoted, causing `cmd.exe` to try and expand them incorrectly before `shx` receives the argument.

fix

Enclose all glob patterns in escaped double quotes, e.g., `shx rm \"*.js\"` within your `package.json` script.

Upgrade

Version history

0.4.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/shelljs/shx ↗

packagehttps://www.npmjs.com/package/shx ↗