Edit

CLI configuration

Install the CLI

yarn add @build-tracker/[email protected]
# or
npm install --save @build-tracker/[email protected]

Adding the @build-tracker/cli package will install a binary available as bt-cli. It can be run with yarn bt-cli or npx bt-cli

To list all commands and help, run yarn bt-cli --help

Configuration

The Build Tracker CLI is easily configured using a cosmiconfig compatible file.

Starting from the current working directory, it will look for the following possible sources, in this order:

1. a build-tracker property in your package.json
2. a .build-tracerrc file
3. a build-tracker.config.js file exporting a JS object

The ..build-trackerrc file (without extension) can be in JSON or YAML format.

Alternately, you can add a filename extension to designate JSON, YAML, or JS format: .build-trackerrc.json, .build-trackerrc.yaml, .build-trackerrc.yml, .build-trackerrc.js. You may want to use an extension so that your text editor can better interpret the file, and help with syntax checking and highlighting.

Once one of these is found and parsed, the search will stop and that object will be used.

The configuration search can also be short-circuited by passing a --config argument with a path to your configuration file.

applicationUrl: string

The full URL (with scheme) to your application. New builds will be posted to the API available at this URL

module.exports = {
  applicationUrl: 'https://build-tracker-demo.herokuapp.com',
  // OR, if you're running from a subdirectory
  applicationUrl: 'https://mysite.dev/build-tracker'
};

artifacts: Array<string>

An array of glob paths to search for your artifacts.

module.exports = {
  artifacts: ['./dist/**/*.js']
};

baseDir?: string = process.cwd()

A base directory option to calculate relative paths for your artifacts. This is most often useful for stripping off unwanted paths, like dist, though it must be an absolute path on your system. This can be most easily accomplished by using the path node API:

module.exports = {
  baseDir: path.join(__dirname, 'dist')
};

cwd?: string = process.cwd()

The command working directory. Set this to change the script working path to something else other than process.cwd()

module.exports = {
  cwd: path.join(__dirname, '..')
};

getFilenameHash?: (filename: string) => string | void

This optional method allows you to extract a filename hash from the built artifact filename. Many applications built with webpack will include a chunk hash in the filename for cache-busting reasons.

It's important to register filename hashes in Build Tracker builds foe each artifact to know if your service is requiring users to redownload files, even though their functional content has not changed.

For example, if your dist folder looks like this:

vendor.a64785b.js
main.56acd2e.js

You can extract the hash from the filename with a function:

module.exports = {
  getFilenameHash: fileName => {
    const parts = path.basename(fileName, '.js').split('.');
    return parts.length > 1 ? parts[parts.length - 1] : null;
  }
};

nameMapper?: (filename: string) => string

Similar to the getFilenameHash method above, you may want to strip out parts of the artifact filenames to make them more legible in reports and the application.

const filenameHash = fileName => {
  const parts = path.basename(fileName, '.js').split('.');
  return parts.length > 1 ? parts[parts.length - 1] : null;
};

module.exports = {
  nameMapper: fileName => {
    const hash = filenameHash(fileName);
    const out = fileName.replace(/\.js$/, '');
    return hash ? out.replace(`.${hash}`, '') : out;
  }
};

buildUrlFormat?: string

You may want to link each build to a commit. Provide buildUrlFormat in the following format to map revision value to an url.

module.exports = {
  buildUrlFormat: 'https://github.com/paularmstrong/build-tracker/commit/:revision'
};

onCompare?: (data: APIResponse) => Promise<void>

Take any action on the response from the API.

module.exports = {
  onCompare: data => {
    // send markdown response somewhere…
    GithubApi.postComment(data.markdown);
    return Promise.resolve();
  }
};

The data response consists of a lot of useful data. Depending on how you want to report information, you may only need part of it.

interface APIResponse {
  build: { meta: BuildMeta; artifacts: Array<Artifact> };
  parentBuild: { meta: BuildMeta; artifacts: Array<Artifact> };
  groupDeltas: Array<ArtifactDelta>;
  artifactDeltas: Array<ArtifactDelta>;
  json: ComparisonMatrix; // Object representation of the build comparison chart
  markdown: string; // Markdown table of the build comparison chart
  csv: string; // CSV formatted string of the build comparison chart
}

Most likely, you'll care about groupDeltas and artifactDeltas. These contain information about every group and artifact in your build, compared to its parent.

interface ArtifactDelta {
  name: string;
  sizes: { [key: string]: number };
  percents: { [key: string]: number };
  hashChanged: boolean;
  budgets: Array<BudgetResult>;
  failingBudgets: Array<BudgetResult>;
}

The failingBudgets on each ArtifactDelta will be an array of budgets that you have configured that have been exceeded in this change.

interface BudgetResult {
  sizeKey: string;
  passing: boolean;
  expected: number;
  actual: number;
  type: Budget['type'];
  level: Budget['level'];
}

Commands

upload-build

This command will read your configuration file, and upload the current build meta and artifact stats to your server. In most scenarios, this should be all you need.

Beside the arguments below, if you're running your server with a BT_API_AUTH_TOKEN environment variable, ensure you run this command with that variable available as well.

BT_API_AUTH_TOKEN=my-secret-token bt-cli upload-build

option, alias	description	default
--branch, -b	Set the branch name and do not attempt to read from git	Current git working branch
--config, -c	Set path to the build-tracker CLI config file	./build-tracker.config.js
--out, -o	Write the build to stdout	true
--skip-dirty-check	Skip the git work tree state check	false

create-build

This command will create a Build object for the current available build. If run independently, it will only output information, but not upload it anywhere. For that, you only need to run yarn bt-cli upload-build.

option, alias	description	default
--branch, -b	Set the branch name and do not attempt to read from git	Current git working branch
--config, -c	Set path to the build-tracker CLI config file	./build-tracker.config.js
--skip-dirty-check	Skip the git work tree state check	false

stat-artifacts

Lower-level than create-build, this command will get artifact stats for the current build files and output a JSON representation of them.

option, alias	description	default
--config, -c	Set path to the build-tracker CLI config file	./build-tracker.config.js
--out, -o	Write the stats to stdout	true

version

Output the version number of the bt-cli.