As an example, let’s create a builder that executes a shell command.

To create a builder, use the `createBuilder()` CLI Builder function, and return a `BuilderOutput` object.

<code-example language="typescript" header="/command/index.ts">

import { BuilderOutput, createBuilder } from '@angular-devkit/architect';

export default createBuilder(_commandBuilder);

function _commandBuilder(

options: JsonObject,

context: BuilderContext,

): Promise<BuilderOutput> {

...

}

<code-example language="typescript" header="/command/index.ts">

import { BuilderOutput, createBuilder } from '@angular-devkit/architect';

import * as childProcess from 'child_process';

export default createBuilder(_commandBuilder);

function _commandBuilder(

options: JsonObject,

context: BuilderContext,

): Promise<BuilderOutput> {

const child = childProcess.spawn(options.command, options.args);

return new Promise<BuilderOutput>(resolve => {

child.on('close', code => {

resolve({success: code === 0});

});

});

}

<code-example language="typescript" header="/command/index.ts">

import { BuilderOutput, createBuilder, BuilderContext } from '@angular-devkit/architect';

import * as childProcess from 'child_process';

export default createBuilder(_commandBuilder);

function _commandBuilder(

options: JsonObject,

context: BuilderContext,

): Promise<BuilderOutput> {

const child = childProcess.spawn(options.command, options.args, {stdio: 'pipe'});

child.stdout.on('data', (data) => {

context.logger.info(data.toString());

});

child.stderr.on('data', (data) => {

context.logger.error(data.toString());

});

return new Promise<BuilderOutput>(resolve => {

child.on('close', code => {

resolve({success: code === 0});

});

});

}

<code-example language="typescript" header="/command/index.ts">

import { BuilderOutput, createBuilder, BuilderContext } from '@angular-devkit/architect';

import * as childProcess from 'child_process';

export default createBuilder(_commandBuilder);

function _commandBuilder(

options: JsonObject,

context: BuilderContext,

): Promise<BuilderOutput> {

context.reportStatus(`Executing "${options.command}"...`);

const child = childProcess.spawn(options.command, options.args, {stdio: 'pipe'});

child.stdout.on('data', (data) => {

context.logger.info(data.toString());

});

child.stderr.on('data', (data) => {

context.logger.error(data.toString());

});

return new Promise<BuilderOutput>(resolve => {

context.reportStatus(`Done.`);

child.on('close', code => {

resolve({success: code === 0});

});

});

}

<code-example language="typescript" header="/command/index.ts">

context.reportStatus(`Executing "${options.command}"...`);

const child = childProcess.spawn(options.command, options.args, { stdio: 'pipe' });

* In the builder source directory, we have created a new test file `index.spec.ts`. The code creates new instances of `JsonSchemaRegistry` (for schema validation), `TestingArchitectHost` (an in-memory implementation of `ArchitectHost`), and `Architect`.

The test uses the builder to run the `ls` command, then validates that it ran successfully and listed the proper files.

<code-example language="typescript" header="command/index_spec.ts">

import { Architect } from '@angular-devkit/architect';

import { TestingArchitectHost } from '@angular-devkit/architect/testing';

// Our builder forwards the STDOUT of the command to the logger.

import { logging, schema } from '@angular-devkit/core';

describe('Command Runner Builder', () => {

let architect: Architect;

let architectHost: TestingArchitectHost;

beforeEach(async () => {

const registry = new schema.CoreSchemaRegistry();

registry.addPostTransform(schema.transforms.addUndefinedDefaults);

// TestingArchitectHost() takes workspace and current directories.

// Since we don't use those, both are the same in this case.

architectHost = new TestingArchitectHost(__dirname, __dirname);

architect = new Architect(architectHost, registry);

// This will either take a Node package name, or a path to the directory

// for the package.json file.

await architectHost.addBuilderFromPackage('..');

});

// This might not work in Windows.

it('can run ls', async () => {

// Create a logger that keeps an array of all messages that were logged.

const logger = new logging.Logger('');

const logs = [];

logger.subscribe(ev => logs.push(ev.message));

// A "run" can have multiple outputs, and contains progress information.

const run = await architect.scheduleBuilder('@example/command-runner:command', {

command: 'ls',

args: [__dirname],

}, { logger }); // We pass the logger for checking later.

// The "result" member (of type BuilderOutput) is the next output.

const output = await run.result;

// Stop the builder from running. This stops Architect from keeping

// the builder-associated states in memory, since builders keep waiting

// to be scheduled.

await run.stop();

// Expect that it succeeded.

expect(output.success).toBe(true);

// Expect that this file was listed. It should be since we're running

// `ls $__dirname`.

expect(logs).toContain('index.spec.ts');

});

});

When running this test in your repo, you need the [`ts-node`](https://github.com/TypeStrong/ts-node) package. You can avoid this by renaming `index.spec.ts` to `index.spec.js`.