Bare Docs

bare-sidecar

Start and manage Bare sidecar processes from Node.js and Electron

Documented against v0.5.16
stable

bare-sidecar — Start and manage Bare sidecar processes from Node.js and Electron.

npm i bare-sidecar

Usage

In the host process:

const Sidecar = require('bare-sidecar')

const sidecar = new Sidecar(require.resolve('./entry'))

sidecar
  .on('exit', (code, status) => {
    // The sidecar process exited
  })
  .on('data', (data) => {
    // Received data from the sidecar over IPC
  })
  .write('Hello sidecar')

In the sidecar entry (entry.js), the IPC channel is available as a stream on Bare.IPC:

Bare.IPC.on('data', (data) => Bare.IPC.write(data))

Standard streams

By default, the standard input, output, and error of the sidecar process are pipes, exposed on the Sidecar as stdin, stdout, and stderr. Piped output must be read, or the sidecar blocks once the pipe buffer fills. The stdio option, added in v0.5.8, lets the sidecar share the streams of the host instead, or discard them:

// Share the standard input, output, and error of the host
const verbose = new Sidecar(require.resolve('./entry'), { stdio: 'inherit' })

// Discard the standard input, output, and error
const quiet = new Sidecar(require.resolve('./entry'), { stdio: 'ignore' })

// Set up each stream on its own, as [stdin, stdout, stderr]
const mixed = new Sidecar(require.resolve('./entry'), { stdio: ['ignore', 'pipe', 'inherit'] })

A stream that is not piped is null on the Sidecar. The IPC channel is not affected by stdio.

API

Sidecar

new Sidecar(entry: string | URL, args?: string[], opts?: SidecarOptions)

Spawn a bundled Bare runtime running entry and return a Sidecar. entry is the path to the module to run, typically resolved with require.resolve(). args is an array of additional command line arguments passed to the process. opts controls how the process is spawned, see SidecarOptions.

Overloads:

new Sidecar(entry: string | URL, args?: string[], opts?: SidecarOptions)
new Sidecar(entry: string | URL, opts?: SidecarOptions)

Parameters

ParameterTypeDefaultDescription
entrystring | URL—Path to the module the sidecar process runs, typically resolved with require.resolve().
args?string[]—Additional command-line arguments passed to the process (default []).
opts?SidecarOptions—Spawn options: detached, and, added in v0.5.8, stdio.

stderr: Pipe | null

The readable standard error stream of the underlying process. It is null when stdio sets the stream to 'inherit' or 'ignore'.

stdin: Pipe | null

The writable standard input stream of the underlying process. It is null when stdio sets the stream to 'inherit' or 'ignore'.

stdout: Pipe | null

The readable standard output stream of the underlying process. It is null when stdio sets the stream to 'inherit' or 'ignore'.

Types

SidecarEvents

interface SidecarEvents {
  exit: [code: number | null, signalCode: string | null]
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}

SidecarOptions

interface SidecarOptions {
  detached?: boolean
  stdio?: SidecarStdio | [stdin?: SidecarStdio, stdout?: SidecarStdio, stderr?: SidecarStdio]
}

Options for new Sidecar().

  • detached: Let the sidecar process lead its own process group. Added in v0.5.6.
  • stdio: How to set up the standard input, output, and error of the sidecar process, either for all three with one SidecarStdio value or per stream with an array of [stdin, stdout, stderr]. Defaults to 'pipe', and so does any array entry that is left out. Added in v0.5.8.

Sidecar.SidecarStdio

type SidecarStdio = 'pipe' | 'inherit' | 'ignore'

How one standard stream of the sidecar process is set up. 'pipe' exposes the stream on the Sidecar, and a piped output stream must be read, or the sidecar blocks once the pipe buffer fills. 'inherit' connects the stream to the matching stream of the host. 'ignore' discards it. Added in v0.5.8.

Sidecar

kill(signal?: string | number): boolean

Send signal to the underlying process, such as 'SIGKILL' to force down a sidecar that destroy() is still waiting on. The sidecar closes once the process has exited.

Parameters

ParameterTypeDefaultDescription
signal?string | number—The signal to send, by name or number (default 'SIGTERM').

Returns boolean — Whether the signal was sent.

Sidecar.versions: SidecarVersions

The versions of the components bundled with the sidecar, such as the Bare runtime.

Types

SidecarVersions

interface SidecarVersions {
  readonly bare: string
}

See also

  • Builds on bare-fs, bare-module, bare-path, bare-pipe, bare-stream, bare-subprocess, and bare-url.
  • The instance extends a duplex stream: writing to it sends data to the sidecar over its IPC channel, data received from the sidecar is emitted as 'data' events, and destroying the stream kills the sidecar process.
  • The 'close' event is emitted after the sidecar process has exited and its underlying stream has been destroyed.
  • The sidecar runs the Bare runtime that ships inside the package, which Sidecar.versions.bare reports: v1.37.1 as of v0.5.16, and v1.36.2 in v0.5.15.
  • bare-subprocess — the lower-level process API.
  • One core, many platforms — running a Bare core beside a host.
  • Bare modules — the full bare-* catalog.
  • Bare runtime API — the runtime these modules extend.

Last updated on

Was this helpful?

On this page