^{Sindre's open source work is supported by the community}

Features

Install

npm install execa

Documentation

Examples

Execution

Simple syntax

import{execa}from'execa';const{stdout}=awaitexeca`npm run build`;// Print command's outputconsole.log(stdout);

Script

import{$}from'execa';const{stdout:name}=await$`cat package.json`.pipe`grep name`;console.log(name);constbranch=await$`git branch --show-current`;await$`dep deploy --branch=${branch}`;awaitPromise.all([$`sleep 1`,$`sleep 2`,$`sleep 3`,]);constdirectoryName='foo bar';await$`mkdir /tmp/${directoryName}`;

Local binaries

$ npm install -D eslint

awaitexeca({preferLocal:true})`eslint`;

Pipe multiple subprocesses

const{stdout, pipedFrom}=awaitexeca`npm run build`.pipe`sort`.pipe`head -n 2`;// Output of `npm run build | sort | head -n 2`console.log(stdout);// Output of `npm run build | sort`console.log(pipedFrom[0].stdout);// Output of `npm run build`console.log(pipedFrom[0].pipedFrom[0].stdout);

Input/output

Interleaved output

const{all}=awaitexeca({all:true})`npm run build`;// stdout + stderr, interleavedconsole.log(all);

Programmatic + terminal output

const{stdout}=awaitexeca({stdout:['pipe','inherit']})`npm run build`;// stdout is also printed to the terminalconsole.log(stdout);

Simple input

constgetInputString=()=>{/* ... */};const{stdout}=awaitexeca({input:getInputString()})`sort`;console.log(stdout);

File input

// Similar to: npm run build < input.txtawaitexeca({stdin:{file:'input.txt'}})`npm run build`;

File output

// Similar to: npm run build > output.txtawaitexeca({stdout:{file:'output.txt'}})`npm run build`;

Split into text lines

const{stdout}=awaitexeca({lines:true})`npm run build`;// Print first 10 linesconsole.log(stdout.slice(0,10).join('\n'));

Streaming

Iterate over text lines

forawait(constlineofexeca`npm run build`){if(line.includes('WARN')){console.warn(line);}}

Transform/filter output

letcount=0;// Filter out secret lines, then prepend the line numberconsttransform=function*(line){if(!line.includes('secret')){yield`[${count++}]${line}`;}};awaitexeca({stdout:transform})`npm run build`;

Web streams

constresponse=awaitfetch('https://example.com');awaitexeca({stdin:response.body})`sort`;

Convert to Duplex stream

import{execa}from'execa';import{pipeline}from'node:stream/promises';import{createReadStream,createWriteStream}from'node:fs';awaitpipeline(createReadStream('./input.txt'),execa`node ./transform.js`.duplex(),createWriteStream('./output.txt'),);

IPC

Exchange messages

// parent.jsimport{execaNode}from'execa';constsubprocess=execaNode`child.js`;awaitsubprocess.sendMessage('Hello from parent');constmessage=awaitsubprocess.getOneMessage();console.log(message);// 'Hello from child'

// child.jsimport{getOneMessage,sendMessage}from'execa';constmessage=awaitgetOneMessage();// 'Hello from parent'constnewMessage=message.replace('parent','child');// 'Hello from child'awaitsendMessage(newMessage);

Any input type

// main.jsimport{execaNode}from'execa';constipcInput=[{task:'lint',ignore:/test\.js/},{task:'copy',files:newSet(['main.js','index.js']),}];awaitexecaNode({ipcInput})`build.js`;

// build.jsimport{getOneMessage}from'execa';constipcInput=awaitgetOneMessage();

Any output type

// main.jsimport{execaNode}from'execa';const{ipcOutput}=awaitexecaNode`build.js`;console.log(ipcOutput[0]);// {kind: 'start', timestamp: date}console.log(ipcOutput[1]);// {kind: 'stop', timestamp: date}

// build.jsimport{sendMessage}from'execa';construnBuild=()=>{/* ... */};awaitsendMessage({kind:'start',timestamp:newDate()});awaitrunBuild();awaitsendMessage({kind:'stop',timestamp:newDate()});

Graceful termination

// main.jsimport{execaNode}from'execa';constcontroller=newAbortController();setTimeout(()=>{controller.abort();},5000);awaitexecaNode({cancelSignal:controller.signal,gracefulCancel:true,})`build.js`;

// build.jsimport{getCancelSignal}from'execa';constcancelSignal=awaitgetCancelSignal();consturl='https://example.com/build/info';constresponse=awaitfetch(url,{signal:cancelSignal});

Debugging

Detailed error

import{execa,ExecaError}from'execa';try{awaitexeca`unknown command`;}catch(error){if(errorinstanceofExecaError){console.log(error);}/*ExecaError: Command failed with ENOENT: unknown commandspawn unknown ENOENTat ...at ... {shortMessage: 'Command failed with ENOENT: unknown command\nspawn unknown ENOENT',originalMessage: 'spawn unknown ENOENT',command: 'unknown command',escapedCommand: 'unknown command',cwd: '/path/to/cwd',durationMs: 28.217566,failed: true,timedOut: false,isCanceled: false,isTerminated: false,isMaxBuffer: false,code: 'ENOENT',stdout: '',stderr: '',stdio: [undefined, '', ''],pipedFrom: [][cause]: Error: spawn unknown ENOENTat ...at ... {errno: -2,code: 'ENOENT',syscall: 'spawn unknown',path: 'unknown',spawnargs: [ 'command' ]}}*/}

Verbose mode

awaitexeca`npm run build`;awaitexeca`npm run test`;

Custom logging

import{execaasexeca_}from'execa';import{createLogger,transports}from'winston';// Log to a file using Winstonconsttransport=newtransports.File({filename:'logs.txt'});constlogger=createLogger({transports:[transport]});constLOG_LEVELS={command:'info',output:'verbose',ipc:'verbose',error:'error',duration:'info',};constexeca=execa_({verbose(verboseLine,{message, ...verboseObject}){constlevel=LOG_LEVELS[verboseObject.type];logger[level](message,verboseObject);},});awaitexeca`npm run build`;awaitexeca`npm run test`;

Related

Maintainers