method

Spawn.SpawnOptions.ipc

message: any,
subprocess: Subprocess<In, Out, Err>,
handle?: unknown
): void;

When specified, Bun opens an IPC channel to the subprocess. The passed callback is called for incoming messages, and subprocess.send can send messages to the subprocess. Messages are serialized using the JSC serialize API, which allows the same types that postMessage/structuredClone supports.

The subprocess can send and receive messages with process.send and process.on("message"), respectively. This is the same API that Node.js exposes when child_process.fork() is used.

This is only compatible with processes that are other bun instances.

@param subprocess

The Subprocess that received the message

Referenced types

interface Subprocess<In extends SpawnOptions.Writable = SpawnOptions.Writable, Out extends SpawnOptions.Readable = SpawnOptions.Readable, Err extends SpawnOptions.Readable = SpawnOptions.Readable>

A process created by Bun.spawn.

The 3 optional type parameters correspond to the stdio array from the options object. Instead of specifying them, use one of these utility types:

  • ReadableSubprocess (any, pipe, pipe)
  • WritableSubprocess (pipe, any, any)
  • PipedSubprocess (pipe, pipe, pipe)
  • NullSubprocess (ignore, ignore, ignore)
  • readonly exitCode: null | number

    Synchronously get the exit code of the process

    null if the process hasn't exited yet

  • readonly exited: Promise<number>

    The exit code of the process

    The promise resolves when the process exits

  • readonly killed: boolean

    Whether the process has exited

  • readonly pid: number

    The process ID of the child process

    const { pid } = Bun.spawn({ cmd: ["echo", "hello"] });
console.log(pid); // 1234
  • readonly readable: ReadableToIO<Out>

    The same value as Subprocess.stdout

    Exists for compatibility with ReadableStream.pipeThrough

  • readonly signalCode: null | Signals

    Synchronously get the signal code of the process

    null if the process never sent a signal code

    To receive signal code changes, use the onExit callback.

    If the signal code is unknown, this is the original signal code number, but that case should never happen in practice.

  • readonly stderr: ReadableToIO<Err>
  • readonly stdin: WritableToIO<In>
  • readonly stdio: [null, null, null, ...null | number[]]

    Extra file descriptors passed to the stdio option.

    Entries beyond index 2 are number for "pipe" and "socket-fd" slots and, on POSIX, for slots where a raw file descriptor was supplied (the same fd is returned). On POSIX, reading this property transfers ownership of any "pipe" fds to the caller, who is then responsible for closing them; the subprocess will not close them. "socket-fd" and raw-fd slots are likewise caller-owned. Other slots — including raw fds on Windows — are null.

  • readonly stdout: ReadableToIO<Out>
  • readonly terminal: undefined | Terminal

    The terminal attached to this subprocess, if spawned with the terminal option. undefined if no terminal was attached.

    When a terminal is attached, stdin, stdout, and stderr return null. Use terminal.write() and the data callback instead.

    const proc = Bun.spawn(["bash"], {
  terminal: { data: (term, data) => console.log(data.toString()) },
});

proc.terminal?.write("echo hello\n");
  • [Symbol.asyncDispose](): PromiseLike<void>;
  • disconnect(): void;

    Disconnect the IPC channel to the subprocess. This is only supported if the subprocess was created with the ipc option.

  • exitCode?: number | Signals
    ): void;

    Kill the process

    @param exitCode

    Exit code or signal to send to the process

  • ref(): void;

    Tell Bun to wait for this process to exit after you already called unref().

    By default, Bun waits for all subprocesses to exit before shutting down

  • Get the resource usage of the process, such as max RSS and CPU time

    Returns undefined until the process has exited

  • message: any
    ): void;

    Send a message to the subprocess. This is only supported if the subprocess was created with the ipc option, and is another instance of bun.

    Messages are serialized using the JSC serialize API, which allows for the same types that postMessage/structuredClone supports.

  • unref(): void;

    Tell Bun not to wait for this process to exit before shutting down.

    By default, Bun waits for all subprocesses to exit before shutting down.