Onboarding: storybookjs/storybook

Generated by RepoPilot · 2026-05-05 · Source

Verdict

GO — Healthy across the board

• Last commit today
• 5 active contributors
• Distributed ownership (top contributor 27%)
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 5 top contributors

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

Storybookjs/storybook is the canonical monorepo for Storybook, a frontend workshop tool that lets developers build, document, and test UI components in complete isolation from the application. It provides a sandbox environment with addons for accessibility testing, controls, interactions, and visual regression, supporting frameworks like React, Vue, Svelte, Angular, and more. The core problem it solves is preventing component development in the context of full pages, which introduces state and environment coupling. This is a large monorepo where framework renderers, core infrastructure, CLI tooling, and addons each live in their own package under a top-level packages/ directory (inferred from the multi-language structure and GitHub Actions setup). The .agents/ and .claude/ directories contain AI agent skill definitions for automated PR review, docs review, canary releases, and upgrade workflows, reflecting a high degree of automation in the contributor workflow.

Who it's for

Frontend engineers and design-system teams at companies of all sizes who need to develop, visually document, and regression-test UI components independently from their main application. Contributors are typically TypeScript/React developers familiar with monorepo tooling (Nx, Yarn workspaces) who want to extend Storybook's addon ecosystem or fix framework-specific rendering issues.

Maturity & risk

Storybook is one of the most widely adopted frontend tooling projects in existence, with tens of thousands of GitHub stars, a CI pipeline on CircleCI (.circleci/config.yml), and active development evidenced by structured GitHub Actions (.github/actions/setup-node-and-install), issue templates, and discussion templates. The codebase is production-ready and battle-tested across thousands of production design systems.

The sheer scale of the monorepo (12M+ lines of TypeScript, 2.5M lines of JavaScript, dozens of framework integrations) means changes can have wide blast radius across many packages. The repo has a large open issue backlog typical of high-profile OSS projects, and the complexity of supporting so many frameworks (React, Vue, Svelte, Angular, Ember, etc.) introduces significant ongoing maintenance risk. Dependency on many third-party bundlers and framework internals means breaking changes in upstream tools (Vite, Webpack, esbuild) frequently require emergency fixes.

Active areas of work

Active work includes AI agent skill development visible in .agents/skills/ and .claude/skills/ (canary releases, GitHub QA labels, PR automation, storybook-upgrade workflows). The .cursor/rules/spy-mocking.mdc file suggests active work on testing conventions. The presence of .cursor/environment.json and .cursor/mcp.json indicates the team is actively integrating AI-assisted development tooling into their contributor experience.

Get running

git clone https://github.com/storybookjs/storybook.git && cd storybook && yarn install && yarn build && yarn dev

Daily commands: yarn dev (starts the development sandbox); yarn build (builds all packages); yarn test (runs the test suite). For a specific framework sandbox: yarn task --task dev --template react-vite/default-ts

Map of the codebase

• .circleci/config.yml — Defines the entire CI/CD pipeline orchestration including build, test, and publish jobs that every contributor's changes must pass through.
• .github/workflows/nx.yml — Primary GitHub Actions workflow leveraging Nx for affected-based builds, gating PRs and determining what gets tested/built.
• .github/workflows/publish.yml — Automates the npm publish pipeline for all Storybook packages, making it critical to understand before any release work.
• .serena/memories/project_overview.md — AI-maintained architectural overview that captures the repo's monorepo structure, key packages, and contributor conventions.
• .serena/memories/style_and_conventions.md — Documents the coding style, naming conventions, and patterns enforced across the monorepo that all contributors must follow.
• .github/workflows/prepare-patch-release.yml — Orchestrates patch release preparation, merging changelogs and version bumps — essential reading before touching any release tooling.
• .lintstagedrc.mjs — Configures pre-commit lint-staged hooks that run on every commit, defining what linting/formatting checks are enforced locally.

How to make changes

Add a new GitHub Actions automation workflow

1. Create a new workflow YAML file in the workflows directory, following existing trigger and job patterns (e.g., referencing the setup-node-and-install composite action). (.github/workflows/nx.yml)
2. If the workflow needs a Node.js script for logic, add it following the existing agent-scan pattern using @actions/core and @actions/github. (.github/scripts/agent-scan-label-pr.mjs)
3. Register any new npm dependencies needed by scripts in the scripts package.json. (.github/scripts/package.json)
4. If using Nx distributed tasks, update the distribution config to allocate agents appropriately. (.nx/workflows/distribution-config.yaml)

Add a new AI agent skill

1. Create a new skill directory under .agents/skills/ with a SKILL.md file defining the skill's purpose, trigger conditions, and step-by-step instructions. (.agents/skills/pr/SKILL.md)
2. If the skill needs reference documentation (style guides, principles), add them under the skill's references/ subdirectory. (.agents/skills/docs-review/references/docs-principles.md)
3. Mirror the skill under framework-specific agent directories (.claude/, .cursor/) if it needs agent-specific adaptations. (.claude/skills/pr/SKILL.md)
4. Update the agent-scan workflow if the skill should be automatically triggered on PRs. (.github/workflows/agent-scan.yml)

Add a new release workflow step

1. Identify whether the change targets patch or non-patch releases and modify the appropriate workflow file. (.github/workflows/prepare-patch-release.yml)
2. If sandbox testing is needed for the new release step, update the sandbox generation workflow. (.github/workflows/generate-sandboxes.yml)
3. Update CircleCI config if the release step requires parallelized jobs or additional CI stages. (.circleci/config.yml)
4. Update the publish workflow if the new step affects what gets pushed to npm. (.github/workflows/publish.yml)

Update contributor/developer documentation and conventions

1. Update the project overview memory file to reflect any architectural changes. (.serena/memories/project_overview.md)
2. Add or update style and convention rules that should be enforced across the monorepo. (.serena/memories/style_and_conventions.md)
3. Add new commonly used commands to the suggested commands memory. (.serena/memories/suggested_commands.md)
4. If a new linting rule is being enforced pre-commit, update the lint-staged configuration. (.lintstagedrc.mjs)

Why these technologies

• Nx — Enables affected-based builds and distributed task execution across a large monorepo with hundreds of packages, dramatically reducing CI time by only rebuilding/retesting what changed.
• CircleCI + GitHub Actions (dual CI) — CircleCI handles heavy parallelized jobs (sandbox generation, cross-framework testing) while GitHub Actions handles PR automation, triage, and lightweight checks — splitting workloads by their nature.
• Yarn (with patches) — Yarn's workspace protocol and patch mechanism allow the monorepo to maintain local package interdependencies and apply fixes to upstream dependencies without forking them.
• Multiple AI agent frameworks (Serena, Claude, Cursor, Copilot) — The repo is intentionally multi-agent to allow different AI assistants to operate with specialized skills, maximizing automation coverage across triage, PR review, and release tasks.
• DangerJS — Enforces PR conventions (changelog entries, file size limits) as code rather than documentation, catching contributor mistakes before human review.

Trade-offs already made

• Dual CI system (CircleCI + GitHub Actions)

  • Why: CircleCI offers better parallelism and artifact handling for long-running jobs; GitHub Actions has tighter GitHub integration for PR automation.
  • Consequence: Contributors must understand two CI systems, and failures can occur in either, increasing debugging surface area.

• Storing AI agent skills as Markdown files in the repo

  • Why: Skills are version-controlled alongside the code they operate on, ensuring agents always use up-to-date instructions
  • Consequence: undefined

Traps & gotchas

The repo uses Yarn (not npm or pnpm) — running npm install will produce broken node_modules due to workspace hoisting differences. Many sandbox tasks require the yarn task CLI with specific --template flags (e.g., react-vite/default-ts) rather than a simple yarn dev. The .env file at root must exist (even if empty) for some build scripts. AI agent skills in .agents/ and .claude/ use separate SKILL.md conventions and must not be conflated with each other despite similar directory structure.

Architecture

Concepts to learn

• Manager/Preview iframe split — Storybook's core architecture isolates component rendering in a sandboxed iframe (preview) from the UI shell (manager), requiring a channel-based postMessage API for communication — understanding this is essential for debugging rendering or addon issues.
• CSF (Component Story Format) — All stories in Storybook are written in CSF, an ES module standard where the default export defines component metadata and named exports define individual stories — this is the canonical data format the entire tool is built around.
• Storybook Addon Channel API — Addons communicate with the preview iframe via a typed event channel (postMessage under the hood), and misunderstanding this async event model is the most common source of addon bugs.
• MDX in component documentation — Storybook uses MDX (Markdown + JSX) for rich documentation pages that can embed live story renderings, and the MDX processing pipeline is custom and differs from standard MDX usage.
• Yarn Workspaces monorepo — All packages are linked via Yarn workspaces, meaning changes to one package are immediately reflected in dependent packages without publishing — misconfiguring this causes phantom dependency bugs that are hard to trace.
• AI Agent Skill files (SKILL.md) — This repo uses structured SKILL.md files in .agents/ and .claude/ to define reusable autonomous agent behaviors for CI tasks like canary publishing and PR review — a non-obvious automation layer that contributors must not bypass.

Related repos

• chromaui/chromatic-cli — Chromatic is the official visual regression testing service built specifically for Storybook stories.
• storybookjs/addon-kit — Official starter kit for building Storybook addons, directly extends this repo's addon API.
• vitejs/vite — Vite is the primary bundler for modern Storybook setups (react-vite, vue-vite templates).
• ladle-dev/ladle — Close alternative to Storybook for React component development, lighter-weight and Vite-native.
• egoist/histoire — Alternative component workshop targeting Vue and Svelte, directly competes with Storybook in those ecosystems.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions workflow to validate agent SKILL.md files for schema consistency

The repo has agent skill definitions in both .agents/skills/ and .claude/skills/ directories, but there is no CI workflow to validate that these SKILL.md files are consistent, well-formed, or that skills present in one directory are mirrored in the other. For example, .agents/skills/ contains docs-review, fix-linting-types-on-pr, and storybook-upgrade but .claude/skills/ is missing docs-review and fix-linting-types-on-pr. A new contributor could add a validation workflow and sync-check script.

• [ ] Audit both .agents/skills/ and .claude/skills/ directories and document the discrepancies (e.g., docs-review and fix-linting-types-on-pr exist only in .agents/skills/)
• [ ] Create a .github/scripts/validate-skills.mjs script (following the existing pattern of .github/scripts/agent-scan-label-pr.mjs) that reads both skill directories and asserts parity between them
• [ ] Add a new GitHub Actions workflow file at .github/workflows/validate-skills.yml that triggers on PRs modifying any file under .agents/skills/** or .claude/skills/** and runs the validation script
• [ ] Update .github/scripts/package.json to include any new dependencies needed by the validation script
• [ ] Add the missing skill directories (e.g., .claude/skills/docs-review/ and .claude/skills/fix-linting-types-on-pr/) with appropriate SKILL.md stubs to resolve the current parity issue

Create a dedicated GitHub Actions workflow for Markdown link checking on docs reference files

The repo already has a .github/workflows/markdown-link-check-config.json config file, which implies some link checking is set up, but there is no visible dedicated workflow file for running this check. More critically, the .agents/skills/docs-review/references/ directory contains important documentation reference files (docs-antipatterns.md, docs-principles.md, docs-strategy.md, storybook-style.md) that guide AI agents and human contributors, but broken external links in these files would silently degrade the quality of agent outputs. A targeted workflow would catch regressions early.

• [ ] Inspect .github/workflows/markdown-link-check-config.json to understand the existing configuration and identify which paths are currently covered
• [ ] Create .github/workflows/markdown-link-check.yml that uses gaurav-nelson/github-action-markdown-link-checker or lycheeverse/lychee-action, scoped specifically to **/*.md files under .agents/, .claude/, and .github/
• [ ] Configure the workflow to use the existing .github/workflows/markdown-link-check-config.json as the config file so settings are shared
• [ ] Add a trigger for pull_request events when any .md file in the above directories is modified, and a weekly schedule trigger to catch link rot on unchanged files
• [ ] Test the workflow by intentionally introducing a broken link in one of the .agents/skills/docs-review/references/*.md files, verifying the CI fails, then reverting the change

Add integration test coverage for the agent-scan-label-pr.mjs GitHub Actions script

The .github/scripts/agent-scan-label-pr.mjs script is the core logic used by the .github/workflows/agent-scan.yml workflow to scan and label PRs, yet there are no corresponding test files in .github/scripts/. This script uses @actions/core and @actions/github (both listed as dependencies in .github/scripts/package.json), which can be mocked in unit tests. Bugs in this script could cause incorrect labels to be applied to community PRs, directly impacting maintainer workflow. Adding tests

Good first issues

1. Add missing test coverage for the spy-mocking conventions defined in .cursor/rules/spy-mocking.mdc — the rule file exists but enforcement via tests may be incomplete. 2. Improve the docs-antipatterns.md reference under .agents/skills/docs-review/references/ by auditing existing MDX story documentation files against the listed antipatterns and submitting fixes. 3. The .github/ISSUE_TEMPLATE/update_docs.yml template exists but the actual docs contribution guide may not reflect the AI agent review workflow — write a CONTRIBUTING_DOCS.md that references the SKILL.md files.

Top contributors

• @ndelangen — 26 commits
• @huang-julien — 23 commits
• @Sidnioulz — 22 commits
• @yannbf — 18 commits
• @JReinhold — 8 commits

Recent commits

• 071eca7 — Merge pull request #34707 from storybookjs/yann/fix-observability (yannbf)
• 9893697 — Merge pull request #34611 from storybookjs/copilot/move-docs-mdx-into-core (JReinhold)
• 1df1a39 — only do cumulative results in self healing loop (yannbf)
• 53e094a — Merge pull request #34403 from storybookjs/julien/tanstack (huang-julien)
• 404e426 — Merge pull request #34665 from storybookjs/norbert/m3-generator-orchestration (ndelangen)
• 1330be2 — Merge branch 'next' into norbert/m3-generator-orchestration (ndelangen)
• 97489ec — Merge pull request #34714 from storybookjs/norbert/fix-windows-rn-tests (ndelangen)
• 5909e3e — Merge remote-tracking branch 'origin/next' into julien/tanstack (huang-julien)
• e8444cf — Merge branch 'next' into norbert/m3-generator-orchestration (ndelangen)
• 860a773 — Merge pull request #34660 from storybookjs/norbert/m1-metro-config-codemod (ndelangen)

Security observations

• High · Presence of .env File in Repository — .env. A .env file is present in the repository root. This file commonly contains sensitive environment variables such as API keys, secrets, database credentials, and tokens. If committed to version control, these secrets become accessible to anyone with repository access, including in git history even after deletion. Fix: Ensure .env is listed in .gitignore and never committed. Use .env.example with placeholder values for documentation. Rotate any secrets that may have been exposed. Use a secrets management solution (e.g., GitHub Actions Secrets, Vault, AWS Secrets Manager) for CI/CD pipelines.
• High · GitHub Actions Workflow Scripts with Potential Injection Risk — .github/workflows/, .github/scripts/agent-scan-label-pr.mjs. The repository contains multiple GitHub Actions workflows (.github/workflows/) and a script (.github/scripts/agent-scan-label-pr.mjs) that interact with GitHub context data (e.g., PR titles, issue bodies, branch names). If untrusted user-supplied data from pull request events is interpolated directly into shell commands or script logic without sanitization, it can lead to expression injection attacks allowing arbitrary code execution in the CI environment. Fix: Never interpolate GitHub context variables (github.event.pull_request.title, github.event.issue.body, etc.) directly into run steps. Use intermediate environment variables set via $GITHUB_ENV or pass data as arguments. Pin third-party actions to full commit SHAs. Restrict workflow permissions to the minimum required (e.g., contents: read). Use environment protection rules for sensitive workflows.
• High · Broad Workflow Trigger Attack Surface (Fork PRs) — .github/workflows/fork-checks.yml. The presence of .github/workflows/fork-checks.yml suggests workflows are triggered by pull_request_target or similar events from forked repositories. This event runs in the context of the base repository (with access to secrets) while potentially executing code from untrusted forks, which is a well-known critical GitHub Actions vulnerability vector. Fix: Avoid using pull_request_target with steps that checkout or execute code from the forking branch. If fork PRs must be handled, use a two-workflow pattern: one workflow with pull_request (no secrets) for CI, and a separate privileged workflow triggered manually or after review approval. Strictly limit the permissions granted to fork-triggered workflows.
• Medium · Unpinned npm Dependencies in GitHub Scripts Package — .github/scripts/package.json. The .github/scripts/package.json uses caret (^) version ranges for @actions/core (^1.11.1) and @actions/github (^6.0.0). This means minor and patch updates are automatically resolved at install time, which could introduce supply chain vulnerabilities if any transitive or direct dependency is compromised without an explicit version lock being enforced. Fix: Pin all dependencies to exact versions (remove the ^ prefix). Commit a lockfile (package-lock.json or yarn.lock) and verify its integrity. Consider using npm ci in CI pipelines. Periodically audit dependencies with npm audit and use Dependabot or Renovate for automated, reviewed updates.
• Medium · AI Agent Skills with Potential for Privilege Escalation — .agents/, .claude/. The repository contains .agents/ and .claude/ directories with SKILL.md files defining automated agent behaviors for tasks like PR management, canary releases, and storybook upgrades. Automated agents with write access to the repository could be manipulated through prompt injection in PR descriptions or issue bodies to perform unintended privileged actions (e.g., publishing releases, modifying labels, merging PRs). Fix: Strictly scope agent permissions to the minimum required. Implement input validation and sanitization for all data fed to agent prompts. Require human approval for sensitive operations (releases, merges). Audit agent action logs regularly. Ensure agent tokens/credentials are scoped and rotated frequently.
• Medium · MCP (Model Context Protocol) Configuration Exposure — .cursor/mcp.json, .github/copilot-mcp.json. The .cursor/mcp.json and .github/copilot-mcp.json files configure Model Context Protocol integrations. These configuration files may contain server endpoints, authentication tokens, or API keys for AI tool integrations. If these files are committed with sensitive values, they represent a credential exposure risk. Fix: Audit these configuration files to ensure no secrets, tokens, or sensitive endpoints are hardcoded. Use environment variable references instead of inline credentials

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.