Skip to content
Web Performance Auditing tooling
TypeScript JavaScript Other
Branch: master
Clone or download
rafaelbernard and mitchellsimoens Docs bitbucket pipelines (#153)
* Add bitbucket pipelines integration example

* Fix name

* Use gimbal docker image

* Fix typo

* Refactor bitbucket custom example and add more examples

* Update complete example file

* Fix gimbal only example
Latest commit f17981a Nov 1, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Support max num routes, fix vcs comment of extra nested data (#142) Aug 9, 2019
.github Move to a monorepo (#109) May 16, 2019
.vscode fix(output): Fix logging output of nested data Jul 2, 2019
action Add GitHub action (#148) Sep 9, 2019
bin Support max num routes, fix vcs comment of extra nested data (#142) Aug 9, 2019
docs Nested list of what docs need to be done (#137) Jul 10, 2019
packages Docs bitbucket pipelines (#153) Nov 1, 2019
.editorconfig chore(ci-init): Implement CI initial architecture Apr 4, 2019
.eslintignore Add an event emitter that handles wildcards (#54) Apr 24, 2019
.eslintrc.js Size module build dir (#146) Sep 5, 2019
.gitignore Docs bitbucket pipelines (#153) Nov 1, 2019
.prettierignore handle object and string versions of jobs in the config (#44) Apr 19, 2019
.prettierrc Fix errors and code smells as reported by sonarcloud (#125) Jun 19, 2019 License + package name + standard files Apr 18, 2019
LICENSE License + package name + standard files Apr 18, 2019 Fix yarn global args order Oct 9, 2019
lerna.json v1.2.6 Oct 11, 2019
package.json Update some deps Oct 11, 2019
tsconfig.json Get modules to work with multiple routes and reconcile to one report (#… Jun 7, 2019
yarn.lock Update some deps Oct 11, 2019

Gimbal - Web Performance Budgeting Automation

npm (scoped) npm CircleCI PRs Welcome MIT Licensed Powered by Modus_Create

Installation | Documentation | Contributing | Code of Conduct | Twitter

Gimbal uses industry-standard audits to analyze application performance. Continuously track performance to ensure your apps are within acceptable 🏎performance budgets.

Gimbal ❤️ CIs like Circle CI, Travis CI, Jenkins, and GitHub Actions.

Getting Started

You can install Gimbal globally using npm or yarn:

# with npm
npm install --global @modus/gimbal

# or with yarn
yarn global add @modus/gimbal

gimbal --help

Now the gimbal is executable throughout your system for any projects you want to audit.

You can also install it to a specific project as a development dependency.

# with npm
npm install --save-dev @modus/gimbal

# or with yarn
yarn add --dev @modus/gimbal

Your project should have been built in order to execute gimbal.

You can execute it via a npm script: (package.json):

  "scripts": {
    "audit": "gimbal audit"
# with npm
npm run audit

# or with yarn
yarn audit


You don't need to Configure Gimbal, but we understand that defaults are optimistic, at least for existing projects that want to introduce performance budgeting.

To ease you be ready to use, let's start with some sample .gimbalrc.yml config files:

  1. Minimal
  2. Minimal with all native audits
  3. Using other audit plugins and more sample configurations

Please, make sure your project was build before executing gimbal.

You may save them as your .gimbalrc.yml file and run gimbal.

1) Minimal sample .gimbalrc.yml config file:

  - size

  buildDir: build

2) Minimal sample .gimbalrc.yml config file running all native audits:

  - size
  - lighthouse
  - heap-snapshot
  - unused-source

  buildDir: build

3) Sample .gimbalrc.yml config file running audit plugins and more configurations:

Before executing this config file you should install mentioned plugins. For instance:

# with npm
npm install @modus/gimbal-plugin-axe @modus/gimbal-plugin-last-value @modus/gimbal-plugin-sqlite

# or with yarn
yarn add @modus/gimbal-plugin-axe @modus/gimbal-plugin-last-value @modus/gimbal-plugin-sqlite

In case you don't use build as your build directory and an exception raises with an error concerning a nonexistent build directory, please create one and run gimbal again.

Config file:

# Specify audits to run. Also include any plugins (like axe)
    - axe
    - size
    - lighthouse
    - heap-snapshot
    - unused-source

    # Only show failures in GitHub PR comments.
    # Useful to pinpoint why a build has failed
    onlyFailures: true

  # Heap snapshot settings
      Documents: 11
      Frames: 5
      JSHeapTotalSize: 13356000
      JSHeapUsedSize: 10068000
      Nodes: 800
      RecalcStyleCount: 15
      LayoutCount: 15

  # Lighthouse settings
      - uses-http2
      - redirects-http
      - uses-long-cache-ttl
      - uses-text-compression
    outputHtml: artifacts/lighthouse.html
      accessibility: 90
      "best-practices": 92
      performance: 64
      pwa: 52
      seo: 100

  # File and directory size settings
    - path: ./build/precache-*.js
      maxSize: 10 KB
    - path: ./build/static/js/[0-9]*.chunk.js
      maxSize: 1 MB
    - path: ./build/static/js/*.chunk.js
      maxSize: 1 MB
    - path: ./build/static/js/runtime*.js
      maxSize: 10 KB
    - path: ./build/index.html
      maxSize: 10 KB
    - path: ./build/favicon.ico
      maxSize: 10 KB
    - path: ./build/
      maxSize: 18 MB

  # Unused source settings
      - path: "**/*(private).*.chunk.css"
        maxSize: 60%
      - path: "**/!(private).*.chunk.css"
        maxSize: 60%
      - path: "**/*([0-9]).*.chunk.js"
        maxSize: 90%
      - path: "**/!([0-9]|main).*.chunk.js"
        maxSize: 45%
      - path: "**/(main).*.chunk.js"
        maxSize: 50%

# Locations of reports. Useful for storing artifacts in CI
  # Only show failures in CLI
    onlyFailures: true
  html: artifacts/results.html
  json: artifacts/results.json
  markdown: artifacts/

# Plugins
  # Compare metrics to last-saved values
  - plugin: "@modus/gimbal-plugin-last-value"
    saveOnlyOnSuccess: false

  # Save reports to a database. Needed for gimbal-plugin-last-value
  - plugin: "@modus/gimbal-plugin-sqlite"
    lastValue: true

  # Axe a11y audits
  - plugin: "@modus/gimbal-plugin-axe"
      aria-allowed-attr: critical
      color-contrast: serious
      landmark-one-main: moderate
      landmark-complementary-is-top-level: moderate
      meta-viewport: critical
      region: moderate
      page-has-heading-one: moderate
      scrollable-region-focusable: moderate

CI Integration

Consult with our docs for sample CI configuration files:


Docker images are available in Docker Hub as moduscreate/gimbal.


This repo is organized as a monorepo that uses Lerna. Packages:

Questions and Support

If you have a problem running Gimbal, please submit an issue. The more information you give us the faster we can get back with a good answer.

Modus Create

Modus Create is a digital product consultancy. We use a distributed team of the best talent in the world to offer a full suite of digital product design-build services; ranging from consumer facing apps, to digital migration, to agile development training, and business transformation.

Modus Create

This project is part of Modus Labs.

Modus Labs


This project is MIT licensed.

You can’t perform that action at this time.