@build-tracker/server package will install a binary available as
bt-server. It can be run with
yarn bt-server or
Important note: It is recommended to do set up your Build Tracker server & application either in a new repository or in an isolated workspace away from the code that you wish to track. This will help you avoid configuration conflicts as well as build-time issues between your app and Build Tracker itself.
To list all commands and help, run
yarn bt-server --help
The Build Tracker application 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:
build-trackerproperty in your
build-tracker.config.jsfile exporting a JS object
.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.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.
Please note that options not denoted with a
? are required and must be provided.
Allows setting budgets for single or groups of artifacts, as well as filtering out and hiding artifacts from viewers.
An object map of artifact names to arrays of budgets for each artifacts.
Artifact budgets can also be given a special key,
'*', that will apply to all artifacts in every build and be merged with any specific budgets:
An array of regular expressions used to hide artifacts from display. This is typically not needed, unless you have artifacts generated by systems that really don't need to be checked.
For example, filter out all translation bundles except for the default:
Have Build Tracker group specific artifacts together so you can track and budget on the sum of the artifacts. This is a great option when you have synchronous and asynchronous artifacts, allowing you to determine the byte-size required for initial page loads.
Separate from individual artifacts, budgets can be set across the sum of all artifacts.
hideAttribution?: boolean = false
true to hide the attribution and link in the Drawer.
name?: string = 'Build Tracker'
If provided, replaces the title Build Tracker in the top application bar.
The URL that your server is running at. Please set this to ensure the application is able to fetch from your database correctly.
Server & application options
defaultBranch?: string = 'main'
Your application will graph this branch by default and ignore builds from other branches.
This is a useful setting if you use and track a branch that is not
main in your git repository.
dev?: boolean = false
Set the server into development mode. This is only recommended if you are contributing to Build Tracker.
Run any custom code after a build has been inserted into the database. The comparator object you receive will compare the new build against the build associated with its own
The default size type used to represent files. For example,
The following options should generally be handled by a Build Tracker plugin. You can always override them or write your own custom queries and DB setup if you like.
setup?: () => Promise<boolean>
If provided, this function is run before the application starts running. Most plugins will do database creation or upgrades during this phase.
The Build Tracker server API uses these methods to fetch and insert builds in the database.
Securing your API
It's easy to see that the API POST endpoint
/api/builds is left completely open. To secure this and ensure that bad actors don't have an easy way to write random data to your database, you can do the following:
When running your server, ensure you have an environment variable set,
When your CI system uploads new builds using the
bt-cli upload-build command, ensure the token is set in that environment as well.
bt-server command has a few commands available. For the most part, you should only ever need
Run the server application. Remember to ensure that an API token environment variable is set to add a layer of security to the API.
Run initial database setup. This method runs only the
setup function provided by the Database Integration section of this document.
This is typically unnecessary to run individually, as
run will also execute this command before starting the application.
For development purposes only! This function will seed your database with fake data so that it's easier to build and test new plugins. This command also requires the package
@build-tracker/fixtures, which is not installed by default. You will need to install it manually.
Output the version number of the