Skip to content

Storybook: Improve resiliency of page navigation during deploys #76635

@aduth

Description

@aduth

What problem does this address?

A user may encounter a Storybook page error when navigating to a story in the Storybook site:

Example:

Failed to fetch dynamically imported module: https://wordpress.github.io/gutenberg/assets/best-practices.story-DdodC5L1.js (edited)

This happens because we use continuous deployment with GitHub Pages. When a user visits the Storybook, the browser is made aware of the JavaScript resources for each story in the site, but for performance reasons it loads them dynamically. But if a fresh deployment of the Storybook site happens after the user has loaded the tab, the JavaScript resources the browser expects to load will be wiped away.

The error goes away after refreshing the page, but it makes for a confusing experience to encounter the error, and it's not obvious that they need to refresh the page.

Related Slack discussion: https://wordpress.slack.com/archives/C02QB2JS7/p1771945229001359

What is your proposed solution?

A few options, in order of ease and general preference:

  • We can catch the Vite loading error and programmatically trigger a page reload like in the example.
  • We can find a way to keep the old files around so that existing sessions are uninterrupted. Our existing GitHub Actions workflow has a keep_files option which works perfectly for this, but we'd need to think about a clean-up process to clean up old files so that we don't perpetually grow files on the gh-pages branch.
  • (Unclear if possible or compatible) We could change the generated asset file paths to use a different technique for cache-busting so that the base file name will continue to be available across versions (e.g. in the example error above, best-practices.story-DdodC5L1.js as best-practices.story.js?DdodC5L1 would maintain cache-busting but ensure the file name is consistent across builds)

Metadata

Metadata

Assignees

No one assigned

    Labels

    StorybookStorybook and its stories for components[Type] EnhancementA suggestion for improvement.

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions