ETT-260: upgrade to storybook 9 #132

carylwyatt · 2025-11-07T20:36:38Z

This was a pretty significant upgrade for storybook, and we got some great new features out of it (visual testing locally and accessibility testing).

Some deprecated add-ons were removed, storybook-test was swapped for addon-vitest (hooray!), and there's a new chromatic add-on for visual testing locally in the browser.

I ran into some issues with storybook rendering our styles during the production build. Everything looked fine in the local storybook (i.e. npm run storybook which loads at localhost:6006), but when the build ran for chromatic, none of the styles were loading (example storybook build on chromatic). We've had issues with bootstrap styles not loading in storybook in the past, but absolutely none of the styles loading was wild. I read many, many pages of documentation and github issues/stack overflows, and in the end it made the most sense to just inject a <link rel="stylesheet"> with our full stylesheet directly into the iframe of storybook. I created a vite custom plugin (in .storybook/main.js) to do exactly that.

Currently, all our stories need a new baseline because of the change in default screen sizes. I'm going to see if I can't clean that up and get the stories to match our current baseline, because that's really annoying.

There shouldn't be any change in our stories outside of swapping old syntax for new.

carylwyatt · 2025-11-07T20:40:05Z

Yesterday when I ran npm run test locally, the 13 (?) firebird vitest tests were passing. But now it's trying to run vitest against storybook so some configuration change must've happened. I'll get that sorted, too.

carylwyatt · 2025-11-13T14:33:49Z

The tests are passing, but the visual diff is off because the viewports were updated. The way viewports are imported and applied changed in version 9, so I probably just need to tinker with those settings. See what I'm talking about here: https://www.chromatic.com/review?appId=656a2bfa011def621f569319&number=132&type=linked&view=changes

carylwyatt · 2025-11-13T16:03:36Z

....aaaaand now I need to update the github action to only take snapshots on PR 🥴 the local visual tests are nice, but they send the snapshots to chromatic which just ate up all our snapshots for the month (from an email):

90% of monthly free snapshots used
During the period starting November 1st, 2025 ending December 1st, 2025, hathitrust used 90% of monthly free snapshots. If you reach the free snapshot limit, UI review and testing will be affected. Update plan to get continuous service and expand test coverage.

carylwyatt · 2025-11-21T15:46:21Z

This has been rebased against main. Then the github action for running tests wouldn't build, so I unfortunately had to rm -rf node_modules and rm package-lock.json, then a npm install to get that fixed.

The latest version of storybook is on chromatic looking great: https://www.chromatic.com/library?appId=656a2bfa011def621f569319&buildNumber=408

carylwyatt · 2025-11-21T16:13:29Z

When I built this on dev-3, the css path wasn't correct and story styles were missing. Locally the assets build at the root of storybook, but in "production," they go to /common/firebird/dist/storybook/, so I had to add a conditional to the storybook vite plugin for that. Now it's built on dev-3: https://dev-3.babel.hathitrust.org/common/firebird/dist/storybook/

carylwyatt · 2025-11-21T16:16:56Z

Without seeing the snapshots/visual diff, I can't know for sure that I fixed 100% of the viewport changes, but those should be easy to update in the future if we want to. It definitely shouldn't block this from being merged.

I'm glad this has been updated, even if it took more work than I originally planned!

carylwyatt · 2025-11-21T16:17:56Z

.github/workflows/chromatic.yml

      - deployment
    tags-ignore:
-      - v0.*
+      - '**'


We don't need chromatic to run a new build on every tag push. It already runs whenever main is updated, so that's good enough.

carylwyatt · 2025-11-21T16:18:59Z

.github/workflows/chromatic.yml

        with:
-          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
+          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
+          onlyChanged: true


This "onlyChanged" option tells Chromatic to only run visual tests on a story if the snapshot differs from the baseline. This will hopefully save me in the future from accidentally running out of our free snapshots.

carylwyatt · 2025-11-21T16:22:44Z

.storybook/main.js

    return mergeConfig(config, {
-      // Your environment configuration here
+      //this plugin is a (hopefully) temporary workaround for storybook not picking up our local styles
+      //we use an alias to reference bootstrap styles and they weren't getting picked up by storybook at all during prod build


Now that I removed the aliases, this explanation doesn't make sense anymore. I'm not really sure why the styles weren't being generated like they used to, and I spent a lot of time trying to figure that out. It's supposed to "just work," and it did in storybook 8, but it's not working anymore. This plugin fixes that problem, so I'm fine with this for now. Maybe when I upgrade to Vite 6/Storybook 10, this problem will be magically resolved.

carylwyatt · 2025-11-21T16:25:04Z

src/js/components/AdvancedSearchForm/AdvancedSearchForm.stories.js


 export const MobileDefault = {
-  parameters: {
+  globals: {


Here's the main update you'll see in these story files.

Storybook 9 changed the way they handle global environment, like the default story viewport size and individual story viewport size. The migration tool handled updating most of these, but it missed maybe 20 that I had to do by hand.

carylwyatt · 2025-11-21T16:26:56Z

chromatic.config.json

@@ -0,0 +1,5 @@
+{


This is a new config file that corresponds to the new visual test add-on for Storybook 9.

carylwyatt · 2025-11-21T16:28:08Z

package.json

  "scripts": {
    "dev": "vite",
-    "test": "vitest",
+    "test": "vitest --project=default",


Storybook 9 now uses vitest instead of jest (hooray!), but it caused some issues when running our existing vitest tests. Adding the --project=default flag has vitest run the non-storybook vitest tests.

carylwyatt · 2025-11-21T16:29:49Z

package.json

+    "storybook": "9.1.16",
    "vite": "^5.4.17",
-    "vitest": "^2.1.9"
+    "vitest": "^3.0.0"


I had to upgrade vitest to v3 to use with Storybook 9. No breaking changes there.

carylwyatt · 2025-11-21T16:32:00Z

vite.config.js

 import fs from 'fs';

 // Find all HTML files and build an object of names and paths to work from
+import { fileURLToPath } from 'node:url';


This was added by the vitest add-on.

carylwyatt · 2025-11-21T16:33:42Z

vite.config.js

-      reporter: 'lcov'
+      reporter: 'lcov',
    },
+    projects: [


Some of these options were added by the storybook vitest add-on, but I had to modify it to get vitest to run our existing vitest tests outside of storybook.

aelkiss

Most of the changes look pretty mechanical and I think you've explained the rest; nothing looks like big enough of a change that I'd have any particular concerns, and I think you covered the mysteries regarding some of the building/testing pretty well in comments.

That said, what's the best way to see a working version -- just to build locally? The link to Storybook Publish (https://656a2bfa011def621f569319-kguyvqyoqp.chromatic.com/) in the checks goes to a version that doesn't seem to be loading styles. Is that a result of hitting the snapshot limit?

carylwyatt · 2025-11-21T21:36:10Z

Most of the changes look pretty mechanical and I think you've explained the rest; nothing looks like big enough of a change that I'd have any particular concerns, and I think you covered the mysteries regarding some of the building/testing pretty well in comments.

That said, what's the best way to see a working version -- just to build locally? The link to Storybook Publish (https://656a2bfa011def621f569319-kguyvqyoqp.chromatic.com/) in the checks goes to a version that doesn't seem to be loading styles. Is that a result of hitting the snapshot limit?

😭 nope, that's because of the "fix" I added for building stories on dev-3. it's building the production version, which has the stylesheet path at /common/firebird/dist/storybook which doesn't exist in chromatic. will have to add an additional flag for staging for dev-3 or something... but i'll get it figured out.

carylwyatt · 2025-11-24T21:31:16Z

@aelkiss I fixed it. Took me way too long to realize I didn't need to write any custom path logic, just a simple relative ./ would do. 😑 Styles are working locally as well as:

Latest chromatic build: https://www.chromatic.com/library?appId=656a2bfa011def621f569319&buildNumber=413
And the styles are loading on dev-3: https://dev-3.babel.hathitrust.org/common/firebird/dist/storybook/

aelkiss · 2025-11-25T13:18:28Z

Looking good to me now! 🚢

upgrade to storybook 9

fd2b969

carylwyatt force-pushed the storybook9 branch from cf5d498 to fd2b969 Compare November 21, 2025 15:39

update package-lock for github action build

aff441c

fix css asset path for production build

79c8276

carylwyatt commented Nov 21, 2025

View reviewed changes

carylwyatt requested a review from aelkiss November 21, 2025 16:35

aelkiss reviewed Nov 21, 2025

View reviewed changes

carylwyatt force-pushed the storybook9 branch from ece60de to edf901d Compare November 24, 2025 21:26

update config for chromatic styles path

a6dd67c

carylwyatt force-pushed the storybook9 branch from edf901d to a6dd67c Compare November 25, 2025 14:47

carylwyatt merged commit af31bf5 into main Nov 25, 2025
3 of 5 checks passed

carylwyatt deleted the storybook9 branch November 25, 2025 16:38

ETT-260: upgrade to storybook 9 #132

ETT-260: upgrade to storybook 9 #132

Uh oh!

Conversation

carylwyatt commented Nov 7, 2025

Uh oh!

carylwyatt commented Nov 7, 2025

Uh oh!

carylwyatt commented Nov 13, 2025

Uh oh!

carylwyatt commented Nov 13, 2025

Uh oh!

carylwyatt commented Nov 21, 2025

Uh oh!

carylwyatt commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

carylwyatt commented Nov 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aelkiss left a comment

Choose a reason for hiding this comment

Uh oh!

carylwyatt commented Nov 21, 2025

Uh oh!

carylwyatt commented Nov 24, 2025

Uh oh!

aelkiss commented Nov 25, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

carylwyatt commented Nov 21, 2025 •

edited

Loading