diff --git a/docs/bash.md b/docs/bash.md index 930b58b09b..31c6a960f9 100644 --- a/docs/bash.md +++ b/docs/bash.md @@ -1269,6 +1269,6 @@ await pRetry(
-[**Next**: 🤓 TypeScript](typescript.md)\ +[**Next**: 🐭 Small packages](small.md)\ [**Previous**: 📎 Windows](windows.md)\ [**Top**: Table of contents](../readme.md#documentation) diff --git a/docs/small.md b/docs/small.md new file mode 100644 index 0000000000..e81ffdd083 --- /dev/null +++ b/docs/small.md @@ -0,0 +1,44 @@ + + + execa logo + +
+ +# 🐭 Small packages + +## `nano-spawn` + +Execa aims to be the best way to run commands on Node.js. It is [very widely used](https://github.com/sindresorhus/execa/network/dependents), [battle-tested](https://github.com/sindresorhus/execa/graphs/contributors) and has a bunch of [features](../readme.md#features). + +However, this means it has a relatively big package size: [![Install size](https://packagephobia.com/badge?p=execa)](https://packagephobia.com/result?p=execa). This should not be a problem in a server-side context, such as a script, a server, or an app. But you might be in an environment requiring small packages, such as a library or a serverless function. + +If so, you can use [nano-spawn](https://github.com/sindresorhus/nano-spawn). It is similar, is maintained by the [same people](https://github.com/sindresorhus/nano-spawn#maintainers), has no dependencies, and a smaller package size: ![npm package minzipped size](https://img.shields.io/bundlejs/size/nano-spawn) [![Install size](https://packagephobia.com/badge?p=nano-spawn)](https://packagephobia.com/result?p=nano-spawn). + +On the other hand, please note `nano-spawn` lacks many features from Execa: [scripts](scripts.md), [template string syntax](execution.md#template-string-syntax), [synchronous execution](execution.md#synchronous-execution), [file input/output](output.md#file-output), [binary input/output](binary.md), [advanced piping](pipe.md), [verbose mode](debugging.md#verbose-mode), [graceful](termination.md#graceful-termination) or [forceful termination](termination.md#forceful-termination), [IPC](ipc.md), [shebangs on Windows](windows.md), [and much more](https://github.com/sindresorhus/nano-spawn/issues/14). + +```js +import spawn from 'nano-spawn'; + +const result = await spawn('npm', ['run', 'build']); +``` + +### `node:child_process` + +Both Execa and nano-spawn are built on top of the [`node:child_process`](https://nodejs.org/api/child_process.html) core module. + +If you'd prefer avoiding adding any dependency, you may use `node:child_process` directly. However, you might miss some basic [features](https://github.com/sindresorhus/nano-spawn#features) that both Execa and nano-spawn provide: [proper error handling](https://github.com/sindresorhus/nano-spawn#subprocesserror), [full Windows support](https://github.com/sindresorhus/nano-spawn#windows-support), [local binaries](https://github.com/sindresorhus/nano-spawn#optionspreferlocal), [piping](https://github.com/sindresorhus/nano-spawn#subprocesspipefile-arguments-options), [lines iteration](https://github.com/sindresorhus/nano-spawn#subprocesssymbolasynciterator), [interleaved output](https://github.com/sindresorhus/nano-spawn#resultoutput), [and more](https://github.com/sindresorhus/nano-spawn#features). + +```js +import {execFile} from 'node:child_process'; +import {promisify} from 'node:util'; + +const pExecFile = promisify(execFile); + +const result = await pExecFile('npm', ['run', 'build']); +``` + +
+ +[**Next**: 🤓 TypeScript](typescript.md)\ +[**Previous**: 🔍 Differences with Bash and zx](bash.md)\ +[**Top**: Table of contents](../readme.md#documentation) diff --git a/docs/typescript.md b/docs/typescript.md index 21bcda8635..e0059a8e7f 100644 --- a/docs/typescript.md +++ b/docs/typescript.md @@ -187,5 +187,5 @@ await execa(options)`npm run build`;
[**Next**: 📔 API reference](api.md)\ -[**Previous**: 🔍 Differences with Bash and zx](bash.md)\ +[**Previous**: 🐭 Small packages](small.md)\ [**Top**: Table of contents](../readme.md#documentation) diff --git a/readme.md b/readme.md index e07e9ca494..84f92222e1 100644 --- a/readme.md +++ b/readme.md @@ -103,6 +103,7 @@ Advanced usage: - 🐛 [Debugging](docs/debugging.md) - 📎 [Windows](docs/windows.md) - 🔍 [Difference with Bash and zx](docs/bash.md) +- 🐭 [Small package size](docs/small.md) - 🤓 [TypeScript](docs/typescript.md) - 📔 [API reference](docs/api.md) @@ -440,6 +441,7 @@ await execa`npm run test`; ## Related +- [nano-spawn](https://github.com/sindresorhus/nano-spawn) - Like Execa but [smaller](docs/small.md) - [gulp-execa](https://github.com/ehmicky/gulp-execa) - Gulp plugin for Execa - [nvexeca](https://github.com/ehmicky/nvexeca) - Run Execa using any Node.js version