Turbosnap

[alexasselin008]

This article is the documentation of the investigation of Turbosnap in Orbit.

What is Turbosnap?

TurboSnap is an advanced Chromatic feature that speeds up builds for faster UI testing and review using Git and Webpack’s dependency graph. It identifies component files and dependencies that have changed, then intelligently snapshots only the stories associated with those changes.

Prerequisites

• Chromatic CLI 5.8+

• Storybook 6.2+

• Webpack (for experimental Vite support, see vite-plugin-turbosnap)

• Stories correctly configured in Storybook’s main.js

• 10 successful builds on CI with at least one accepted

• For GitHub Actions: run on push rather than pull_request (learn more)

Configuration

To enable TurboSnap for your project, add the --only-changed flag to your chromatic script, or add the onlyChanged: true option to your GitHub workflow config.

Full rebuilds

Certain circumstances could potentially affect all stories. To prevent false positives, Turbosnap re-test everything if any of the following situations apply:

• Changes to dependency versions in package.json, if no valid lockfile is available

• Changes to your Storybook’s configuration

• Changes in files that are imported by your preview.js (as this could affect any story)

Enable or disable for specific branches

To enable TurboSnap for specific branches, pass a glob to --only-changed (e.g., chromatic --only-changed "feature/*"). Use a negating glob (e.g. chromatic --only-changed "!(main)") to enable all but certain branches. See picomatch for details.

A storybook developer suggested using this tool to test picomatch path: React App

Ignore certain files

Similar to source code changes, the --untraced flag can also be used to ignore dependency updates (e.g., --untraced "services/backend/package.json"). That way, any dependency updates in that package will not be considered when applying TurboSnap

Github CI Setup

Chromatic only run on Main and Active PRs only
chromatic-cli/chromatic-main-and-prs.yml at main · chromaui/chromatic-cli

on:
  push:
    branches:
      - main
  pull_request:
    types: [assigned, ready_for_review, review_requested]

Skip CI on draft pull request

      - uses: chromaui/action@v1
        with:
          # 👇 Chromatic projectToken, refer to the manage page to obtain it.
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          ....
          skip: ${{ github.event.pull_request.draft == true }}

Run full rebuilds on main, but run turbosnap on PRs

onlyChanged: '!(main)'

Improving Change Detection for CSS Files

In Orbit, all the CSS files are merged into a single index.css file that must be imported by the application:

@import "@sharegate/orbit-ui/index.css";

This method of exporting CSS means that components have no direct link to CSS files, and Webpack cannot properly detect stories that were changed by CSS updates. There are two ways to address this issue:

Option 1: Full Rebuild on Every CSS Change

One solution is to use the --external CLI option in Turbosnap, which specifies files that trigger a full rebuild. We could set --external to *.css and rebuild the entire application on every CSS change. However, this approach is not optimal as CSS files are often changed.

Option 2: Change the Way CSS Files are Imported

Instead of exporting all the CSS in a single index.css file, each component should import the CSS that affects it directly. By doing so, Webpack is able to detect changes in CSS and link them to a specific component, as well as to Storybook stories. There was issues in Orbit with the CSS selector priorities, so implementing this solution requires some effort and a lot of testing. The selector issues are slightly documented here.