ShellJS — Portable Unix Shell Commands for Node.js

Introduction

ShellJS is a portable implementation of Unix shell commands written entirely in JavaScript for Node.js. It allows developers to write cross-platform shell scripts without relying on platform-specific shells, making build scripts and automation work identically on Linux, macOS, and Windows.

What ShellJS Does

• Implements common Unix commands like cp, rm, mv, mkdir, cat, grep, and sed in JavaScript
• Provides a synchronous API that mirrors traditional shell scripting patterns
• Runs identically on Windows, macOS, and Linux without shell dependencies
• Offers glob pattern matching for file operations
• Supports command chaining and piping between operations

Architecture Overview

ShellJS re-implements each Unix command as a pure JavaScript function using Node.js built-in modules like fs, path, and child_process. The synchronous design keeps scripts readable and sequential. File operations use Node.js fs APIs directly, while exec() wraps child_process.execSync for external commands.

Self-Hosting & Configuration

• Install with npm install shelljs in any Node.js project
• Require with const shell = require('shelljs') or use ES module import
• Enable silent mode with shell.config.silent = true to suppress output
• Set shell.config.fatal = true to throw errors on command failure
• Use shell.which('git') to check if external tools are available before use

Key Features

• No external dependencies: every command is pure JavaScript
• Familiar Unix syntax reduces the learning curve for shell scripters
• Synchronous execution model simplifies scripting logic
• Built-in glob support for file matching patterns
• Pipe support via .to() and .toEnd() for output redirection

Comparison with Similar Tools

• zx — async-first with modern syntax; ShellJS is synchronous and CommonJS-based
• Execa — focuses on process spawning; ShellJS reimplements shell built-ins natively
• Bash scripts — platform-dependent; ShellJS works on any OS with Node.js
• cross-env — only handles environment variables; ShellJS covers the full shell command set
• Node.js fs module — low-level API; ShellJS provides high-level shell-like abstractions

FAQ

Q: Does ShellJS require Bash or any system shell? A: No. All commands except exec() are implemented in pure JavaScript and require no system shell.

Q: Can I use ShellJS with ES modules? A: Yes. ShellJS supports both CommonJS require and ES module import syntax.

Q: Is ShellJS suitable for production build scripts? A: Yes. It is widely used in CI/CD pipelines and npm scripts for cross-platform build automation.

Q: How does error handling work? A: Each command returns an object with a code property. Set config.fatal = true to throw on non-zero exit codes.

Sources

• https://github.com/shelljs/shelljs
• https://www.npmjs.com/package/shelljs