README.md

Gimbal - Web Performance Budgeting Automation

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

Configuration

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:

audits:
  - size

configs:
  buildDir: build

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

audits:
  - size
  - lighthouse
  - heap-snapshot
  - unused-source

configs:
  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)
audits:
    - axe
    - size
    - lighthouse
    - heap-snapshot
    - unused-source

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

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

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

  # File and directory size settings
  size:
    - 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
  unused-source:
    threshold:
      - 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
outputs:
  # Only show failures in CLI
  cli:
    onlyFailures: true
  html: artifacts/results.html
  json: artifacts/results.json
  markdown: artifacts/results.md

# Plugins
plugins:
  # Compare metrics to last-saved values
  # Install the Last Value plugin with
  #     npm i @modus/gimbal-plugin-last-value --save-dev 
  - plugin: "@modus/gimbal-plugin-last-value"
    saveOnlyOnSuccess: false

  # Save reports to a database. Needed for gimbal-plugin-last-value
  # Install the Sqlite plugin with
  #     npm i @modus/gimbal-plugin-sqlite --save-dev 
  - plugin: "@modus/gimbal-plugin-sqlite"
    lastValue: true

  # Axe a11y audits
  # Install Axe plugin with
  #     npm i @modus/gimbal-plugin-axe --save-dev 
  - plugin: "@modus/gimbal-plugin-axe"
    thresholds:
      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:

• GitHub Actions
• Circle CI
• Travis CI

Docker

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

Packages

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

• Gimbal
• Gimbal Core
• Axe Plugin
• Last Value Plugin
• MySQL Plugin
• SQLite Plugin

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.

How to Improve Web Application Speed and Increase Revenue with Gimbal

Manage UI Performance Budgets with Gimbal

How to Develop High Performing Web Applications

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.

This project is part of Modus Labs.

Licensing

This project is MIT licensed.