Gimbal - Web Performance Budgeting Automation
Installation | Documentation | Contributing | Code of Conduct | Twitter
Gimbal
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 --helpNow 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/gimbalYour 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 auditConfiguration
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:
- Minimal
- Minimal with all native audits
- 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: build2) Minimal sample .gimbalrc.yml config file running all native audits:
audits:
- size
- lighthouse
- heap-snapshot
- unused-source
configs:
buildDir: build3) 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-sqliteIn 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:
Docker
Docker images are available in Docker Hub as moduscreate/gimbal.
Packages
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.
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.