From 60cb78e34c83715dedd3cc3c83f04f5fa878547f Mon Sep 17 00:00:00 2001
From: ehmicky <ehmicky@gmail.com>
Date: Sun, 15 Sep 2024 23:22:50 +0100
Subject: [PATCH] Add documentation about nano-spawn

---
 docs/bash.md       |  2 +-
 docs/small.md      | 38 ++++++++++++++++++++++++++++++++++++++
 docs/typescript.md |  2 +-
 readme.md          |  2 ++
 4 files changed, 42 insertions(+), 2 deletions(-)
 create mode 100644 docs/small.md

diff --git a/docs/bash.md b/docs/bash.md
index 930b58b09b..e9707e4774 100644
--- a/docs/bash.md
+++ b/docs/bash.md
@@ -1269,6 +1269,6 @@ await pRetry(
 
 <hr>
 
-[**Next**: 🤓 TypeScript](typescript.md)\
+[**Next**: 🐭 Small package size](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..2624c3ae36
--- /dev/null
+++ b/docs/small.md
@@ -0,0 +1,38 @@
+<picture>
+	<source media="(prefers-color-scheme: dark)" srcset="../media/logo_dark.svg">
+	<img alt="execa logo" src="../media/logo.svg" width="400">
+</picture>
+<br>
+
+# 🐭 Small package size
+
+## `nano-spawn`
+
+Execa aims to be the best way to run commands on Node.js. It is [very widely used](../../../network/dependents), [battle-tested](../../../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).
+
+### `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']);
+```
+
+<hr>
+
+[**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..7f3dd69afd 100644
--- a/docs/typescript.md
+++ b/docs/typescript.md
@@ -187,5 +187,5 @@ await execa(options)`npm run build`;
 <hr>
 
 [**Next**: 📔 API reference](api.md)\
-[**Previous**: 🔍 Differences with Bash and zx](bash.md)\
+[**Previous**: 🐭 Small package size](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