Installation | Documentation | Contributing | Code of Conduct | Twitter
Gimbal ❤️ CIs like Circle CI, Travis CI, Jenkins, and GitHub Actions.
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:
- 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.
audits: - size configs: buildDir: build
audits: - size - lighthouse - heap-snapshot - unused-source configs: buildDir: build
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
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:
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 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.
This project is MIT licensed.