Skip to content

[docs] add warnings about input, stdin, and stdio #1220

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
jedwards1211 wants to merge 1 commit into from
+42 −0
Closed

[docs] add warnings about input, stdin, and stdio #1220

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions docs/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -759,6 +759,9 @@ _Type:_ `object`

This lists all options for [`execa()`](#execafile-arguments-options) and the [other methods](#methods).

> [!IMPORTANT] Differences from `child_process.spawn` API
> - `stdio: [..., 'ipc']` is deprecated and will produce a runtime error in version 10
Copy link
Collaborator

@ehmicky ehmicky Dec 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you please remove both > and [!IMPORTANT]/[!NOTE]? It's not a bad thing, but it's not consistent with the rest of the documentation, which does not use this style. Thanks!


The following options [can specify different values](output.md#stdoutstderr-specific-options) for [`stdout`](#optionsstdout) and [`stderr`](#optionsstderr): [`verbose`](#optionsverbose), [`lines`](#optionslines), [`stripFinalNewline`](#optionsstripfinalnewline), [`buffer`](#optionsbuffer), [`maxBuffer`](#optionsmaxbuffer).

### options.preferLocal
Expand Down Expand Up @@ -865,6 +868,10 @@ Write some input to the subprocess' [`stdin`](https://en.wikipedia.org/wiki/Stan

See also the [`inputFile`](#optionsinputfile) and [`stdin`](#optionsstdin) options.

> [!NOTE]
> Be careful when combining `input` with `stdin: 'inherit'` or `stdio: 'inherit'`;
> See [this section](input.md#combining-input-with-stdin-inherit) for details.

[More info.](input.md#string-input)

### options.inputFile
Expand All @@ -877,6 +884,10 @@ See also the [`input`](#optionsinput) and [`stdin`](#optionsstdin) options.

[More info.](input.md#file-input)

> [!NOTE]
> Be careful when combining `inputFile` with `stdin: 'inherit'` or `stdio: 'inherit'`;
> See [this section](input.md#combining-input-with-stdin-inherit) for details.

### options.stdin

_TypeScript:_ [`StdinOption`](typescript.md) or [`StdinSyncOption`](typescript.md)\
Expand Down Expand Up @@ -925,6 +936,9 @@ A single string can be used [as a shortcut](output.md#shortcut).

The array can have more than 3 items, to create [additional file descriptors](output.md#additional-file-descriptors) beyond [`stdin`](#optionsstdin)/[`stdout`](#optionsstdout)/[`stderr`](#optionsstderr).

> [!IMPORTANT] Differences from `child_process.spawn` API
> - `stdio: [..., 'ipc']` is deprecated and will produce a runtime error in version 10
Copy link
Collaborator

@ehmicky ehmicky Dec 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Execa has quite a lot of features, which can make its documentation a little overwhelming. So we're making sure the documentation remains concise and we typically explain each piece of information only once. We also mostly avoid repeating between the api.md and rest of the documentation, and rely on users following the "More info" link instead.

Based on this, could you please write the information related to ipc in a single place, as opposed to three? The best place would be ipc.md.

Copy link
Author

@jedwards1211 jedwards1211 Dec 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't really want to; this is the warning I would want to see as a busy developer already familiar with the child_process API encountering this library for the first time. I see burying the warning as a disservice to other experienced developers. I find it kind of annoying that y'all don't seem concerned that having subtle differences is going to cause some developers frustration

Copy link
Author

@jedwards1211 jedwards1211 Dec 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe I should calm down, but I guess the other thing that bothers me is, it's a real shame to abandon being a superset of the child_process.spawn API, that was a nice feature to me because that API is much simpler than execa has become and well known, so at least I can be sure what I'm getting in cases when I don't use any of execa's additional options. Maybe I should just go back to my old package that's a thinner clone of child_process plus promises...


More info on [available values](output.md), [streaming](streams.md) and [transforms](transform.md).

### options.all
Expand Down
28 changes: 28 additions & 0 deletions docs/input.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,10 @@ If the input is already available as a string, it can be passed directly to the
await execa({input: 'stdinInput'})`npm run scaffold`;
```

> [!NOTE]
> Be careful when combining `input` with `stdin: 'inherit'` or `stdio: 'inherit'`;
> See [this section](#combining-input-with-stdin-inherit) for details.

The [`stdin`](api.md#optionsstdin) option can also be used, although the string must be wrapped in two arrays for [syntax reasons](output.md#multiple-targets).

```js
Expand All @@ -82,6 +86,10 @@ await execa({stdin: {file: 'input.txt'}})`npm run scaffold`;
await execa({stdin: new URL('file:///path/to/input.txt')})`npm run scaffold`;
```

> [!NOTE]
> Be careful when combining `inputFile` with `stdin: 'inherit'` or `stdio: 'inherit'`;
> See [this section](#combining-input-with-stdin-inherit) for details.

## Terminal input

The parent process' input can be re-used in the subprocess by passing `'inherit'`. This is especially useful to receive interactive input in command line applications.
Expand All @@ -90,6 +98,10 @@ The parent process' input can be re-used in the subprocess by passing `'inherit'
await execa({stdin: 'inherit'})`npm run scaffold`;
```

> [!NOTE]
> Be careful when combining `input` with `stdin: 'inherit'` or `stdio: 'inherit'`;
> See [this section](#combining-input-with-stdin-inherit) for details.
Copy link
Collaborator

@ehmicky ehmicky Dec 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For concision, let's assume users read this file in its entirety. If so, they will read that section below, so we do not need to point to it from those 3 sections above (and also the 2 places in api.md). This will also help keep this documentation page concise.

Copy link
Author

@jedwards1211 jedwards1211 Dec 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we move the section higher in the document then? I'm trying to look out for busy devs like me who just tend to skim for what we're looking for.

Again, because the API has been a superset of child_process.spawn, I really think devs can be forgiven for assuming they can get away without much RTFM in a case like this


## Any input type

If the subprocess [uses Node.js](node.md), [almost any type](ipc.md#message-type) can be passed to the subprocess using the [`ipcInput`](ipc.md#send-an-initial-message) option. The subprocess retrieves that input using [`getOneMessage()`](api.md#getonemessagegetonemessageoptions).
Expand All @@ -114,6 +126,9 @@ const ipcInput = await getOneMessage();

## Additional file descriptors

> [!IMPORTANT] Differences from `child_process.spawn` API
> - `stdio: [..., 'ipc']` is deprecated and will produce a runtime error in version 10

The [`stdio`](api.md#optionsstdio) option can be used to pass some input to any [file descriptor](https://en.wikipedia.org/wiki/File_descriptor), as opposed to only [`stdin`](api.md#optionsstdin).

```js
Expand All @@ -123,6 +138,19 @@ await execa({
})`npm run build`;
```

## Combining `input` with `stdin: 'inherit'`

> [!WARNING]
> If `input` and `stdin: 'inherit'` (or `stdio: 'inherit'` or `stdio: ['inherit', ...]`) are combined,
> the child will not inherit the parent's `stdin` and `execa` will pipe both `input` and the parent's
> `stdin` to the child's `stdin`.
>
> Therefore the child's `stdin` will not be a TTY and will not close before the parent's `process.stdin`
> in this case.
>
> Version 10 will drop the behavior of piping the parent's `process.stdin` to the child, hence its `stdin`
> will close once `input` has been piped.

<hr>

[**Next**: 📢 Output](output.md)\
Expand Down