# Execa — Process Execution for Humans in Node.js

> A modern process execution library for Node.js that improves on child_process with better defaults, a Promise-based API, and ergonomic pipe and stream handling.

## Install

Save in your project root:

# Execa — Process Execution for Humans in Node.js

## Quick Use
```bash
npm install execa
```
```javascript
import { $ } from 'execa';

// Simple command
const { stdout } = await $`git log --oneline -5`;
console.log(stdout);

// Piping
const result = await $`cat package.json`.pipe`grep name`;
console.log(result.stdout);
```

## Introduction
Execa is a process execution library by Sindre Sorhus that replaces Node.js child_process with a developer-friendly API. It provides sensible defaults, a Promise-based interface, tagged template literal syntax for shell commands, and first-class support for piping and streaming, making subprocess management in Node.js straightforward and reliable.

## What Execa Does
- Executes shell commands and binaries with a clean Promise-based API
- Provides a tagged template literal syntax via `$` for ergonomic command construction
- Pipes processes together with type-safe `.pipe()` chaining
- Handles stdout, stderr, and stdin as strings, buffers, or streams automatically
- Offers detailed error objects with command, exit code, stdout, stderr, and timing

## Architecture Overview
Execa wraps Node.js child_process.spawn with an enhanced Promise that resolves with structured result objects. The tagged template literal parser handles argument escaping and splitting. Pipes are implemented by connecting the stdout readable stream of one process to the stdin writable stream of the next. The library normalizes cross-platform behavior for signals, encoding, and line endings.

## Self-Hosting & Configuration
- Install with `npm install execa` (ESM only since v8)
- Import the `$` function for tagged template syntax or `execa()` for programmatic usage
- Set `shell: true` to run commands through the system shell when needed
- Configure `timeout`, `maxBuffer`, and `encoding` as options per command
- Use `$.sync` for synchronous execution when async is not suitable

## Key Features
- Tagged template literal `$` syntax with automatic argument escaping
- Process piping with `.pipe()` chaining for composing command pipelines
- Detailed error objects include command, exit code, stdout, stderr, and duration
- Cross-platform normalization for signals, line endings, and path handling
- Streaming support: consume stdout/stderr as async iterables or Node.js streams

## Comparison with Similar Tools
- **child_process** — low-level with callback API; Execa adds Promises, piping, and better defaults
- **zx** — shell scripting tool with built-in utilities; Execa is a focused process execution library
- **ShellJS** — synchronous shell command reimplementation; Execa is async and spawns real processes
- **cross-spawn** — fixes Windows spawn issues; Execa includes cross-spawn fixes and adds much more
- **Bun.spawn** — Bun-specific; Execa works across Node.js, Deno, and Bun

## FAQ
**Q: Does Execa work with CommonJS?**
A: Since version 8, Execa is ESM-only. Use version 7 for CommonJS projects or add `"type": "module"` to package.json.

**Q: How does Execa handle errors?**
A: Non-zero exit codes throw an error object containing the command, exit code, stdout, stderr, signal, and duration.

**Q: Can I pipe multiple processes together?**
A: Yes. Use `.pipe()` to chain processes: `await $`cmd1`.pipe`cmd2`.pipe`cmd3``.

**Q: Is Execa faster than child_process?**
A: Performance is similar since both use spawn. Execa adds ergonomics and safety, not raw speed.

## Sources
- https://github.com/sindresorhus/execa
- https://www.npmjs.com/package/execa

---
Source: https://tokrepo.com/en/workflows/asset-774709e9
Author: AI Open Source