Storybook Sync

Storybook Upstream Sync Checker

Analyze recent changes in the official storybookjs/storybook repository and identify which ones may need to be synced to this storybook-rsbuild repo. The storybook-rsbuild project adapts Storybook's official builder and framework packages to work with Rsbuild, so when upstream changes builder-webpack5, builder-vite, or framework integrations, those changes may need to be reflected here.

Upstream to Local Package Mapping

+----------------------------------------+--------------------------------------+
| Upstream (storybookjs/storybook)       | Local (storybook-rsbuild)            |
+----------------------------------------+--------------------------------------+
| code/builders/builder-webpack5         | packages/builder-rsbuild             |
| code/builders/builder-vite             | packages/builder-rsbuild             |
| code/frameworks/react-vite             | packages/framework-react             |
| code/frameworks/react-webpack5         | packages/framework-react             |
| code/frameworks/vue3-vite              | packages/framework-vue3              |
| code/frameworks/web-components-vite    | packages/framework-web-components    |
| code/frameworks/html-vite              | packages/framework-html              |
| code/presets/react-webpack             | packages/framework-react             |
| code/lib/core-webpack                  | packages/builder-rsbuild (prebundled)|
+----------------------------------------+--------------------------------------+

Both webpack5 and vite upstream variants are monitored because this repo borrows patterns from both.

This table defines watch scope — which upstream directories are scanned for commits. Counterpart questions ("does this file have a local port?") are answered at file granularity by .agents/skills/storybook-check/manifest.json (mappings), which also records each file's accepted intentional divergences. Packages listed here but absent from the manifest (builder-vite, core-webpack) are pattern sources rather than ports: triage judges their commits case by case for semantic relevance, and the manifest intentionally carries no entries for them — file-level mappings only make sense where a real port exists.

Upstream Commit History is Noisy

The Storybook repo uses a non-linear branching model with frequent merge commits and automated version bumps. The bundled script filters the most common noise automatically (version bump commits via --invert-grep, merge commits via --no-merges). Some noise may still slip through — NX upgrades, CI config, non-standard version bumps, reverts that cancel out.

Always judge from the actual diff. Storybook does not consistently follow conventional commits, so commit messages are unreliable for triage decisions.

Sync Priority Criteria

A wrong skip is the most expensive mistake this workflow can make: the next run starts after this range, so a skipped commit is never seen again, and the miss stays invisible until it resurfaces as a user-facing bug. When torn between two priorities, take the higher one.

High — sync soon:

• Bug fixes in logic that was adapted into storybook-rsbuild
• Security patches
• API / type / interface changes (options, preset signatures, exports)
• Breaking changes or deprecations

Medium — review and decide:

• New features that could benefit storybook-rsbuild users
• Significant refactoring of adapted code patterns
• Performance improvements in shared logic

Low — nice to know:

• Minor code quality improvements
• Added error handling or edge-case guards
• Test changes that reveal expected behavioral contracts

Skip:

• Superseded by a later commit in this range — its lines were rewritten by a commit that is reported; the Skipped entry must name that commit. Test cases it added survive into the end state and are judged with the reported commit.
• Already present in the local counterpart — the local file already carries the same change (ported ahead of the sync or via another upstream commit). Cite the local file:line in the report entry.
• Covered by a still-valid intentional divergence — the touched file's manifest entry has an intentionalDivergences item that names this behavior, AND you re-verified against the current local file that the divergence's stated reason still holds (e.g. "no rspack counterpart" is still true). Quote the divergence in the report entry. If the reason no longer holds, this is not a skip: classify normally and say the manifest entry is stale and must be updated in the port PR.
• Webpack/Vite internal plumbing with no Rsbuild parallel (e.g. webpack plugin hooks, Vite-specific HMR wiring, Vite module graph internals). This label makes a factual claim — that no local counterpart exists — so earn it before using it: look up every touched file in .agents/skills/storybook-check/manifest.json (mappings) and ignoredUpstreamFiles (files intentionally never ported — the strongest skip evidence). A mappings entry with local: null is not an absence of coverage: its reviewWith and note fields name the local package and what to review. For files the manifest doesn't list, check for a same-purpose local file. If any touched file has a counterpart, the "no Rsbuild parallel" claim is false; unless another Skip criterion applies, the commit is at least medium (high for bug fixes). Commit messages and file paths are not evidence here: files under builder-webpack5/src/plugins/ and src/loaders/ read as webpack-specific by path, yet are ported 1:1 into this repo.
• Documentation-only changes
• CI/tooling changes internal to the Storybook repo
• Changes to storybook/internal/* APIs (these arrive via the storybook npm dependency, not by manual sync)
• Pure test file additions with no behavioral insight
• Build system changes (NX, workspace config, import rewriting) that are specific to the Storybook monorepo structure

Workflow

<skill-dir> below means .agents/skills/storybook-sync (use an absolute path when the command is copied into a subagent prompt). Shell variables do not persist between tool calls: run each step's commands in one shell, or re-inline the values (including REPORT_NAME, which steps 4 and 5 reuse). Snippets are bash (process substitution, $'\t'); run them under bash, not the login shell.

Every run covers the range from ANCHOR through TARGET on upstream next. Both ends are git refs (tag or sha, treated identically) and must be reachable from origin/next: patch tags live on main via cherry-picks; their source commits are on next. The anchor is the last commit the previous report covered, so the range excludes it (ANCHOR..TARGET).

1. Determine the range

TARGET (end ref) — always user-specified. Every run is user-triggered and the user names the target: a tag (v11.0.0, v11.0.0-alpha.3) or a commit sha. Never pick a target yourself; if the user gave none, ask for one.

ANCHOR (start ref) — continue from the last sync report by default. The storybook sync report label is fixed and used for every report this skill publishes.

1. TARGET=<the ref the user named> (a tag or commit sha).
2. If the user also named a start ref: ANCHOR=<that ref>, leave PREV_ISSUE_NUMBER empty (the report is not continuing from an issue), and skip item 3 below (anchor recovery).
3. Otherwise recover the previous report's anchor:

   read -r PREV_ISSUE_NUMBER ANCHOR < <(gh issue list --repo rstackjs/storybook-rsbuild \
     --state all --label "storybook sync report" --limit 1 --json number,body \
     --jq '.[0] | select(.) | "\(.number) \((.body | capture("<!-- storybook-sync: target=(?<sha>[a-f0-9]{40}) -->").sha) // "")"')

   Three outcomes: both set → continue; PREV_ISSUE_NUMBER set but ANCHOR empty → the newest report (#N) has no parseable marker (it predates the marker, or the line was edited); nothing set → no prior report exists. In either empty case, stop and ask the user for a start ref, saying which case applies.

Resolve both ends (this also fetches the cache and validates the refs):

{ IFS=$'\t' read -r ANCHOR_SHA ANCHOR_LABEL; IFS=$'\t' read -r TARGET_SHA TARGET_LABEL; } \
  < <(bash <skill-dir>/scripts/fetch_upstream.sh --resolve "$ANCHOR" "$TARGET")
REPORT_NAME="upstream-sync-report-${ANCHOR_LABEL//\//-}-${TARGET_LABEL//\//-}.md"

Labels come from the script: the ref as written, or an 8-char sha for a bare commit.