Contributing to Storybook

Purpose and Scope

Storybook is a community-oriented open source project, and contribution work ranges from small bug fixes to larger feature proposals. This page orients contributors who want to change the Storybook monorepo itself: how to prepare a local checkout, how the sandbox-based development model works, and how to verify the repository before opening a pull request. The code contribution docs focus on practical setup rather than governance, so this page treats RFCs, documentation contributions, framework contributions, and reproductions as adjacent contribution paths that should be chosen before starting implementation work.

Sources: docs/contribute/code.mdx

For code changes, the central idea is that Storybook development happens against realistic template projects called sandboxes. A sandbox is a generated Storybook environment that represents a user setup, such as a React project built with Vite. Contributors use these sandboxes to exercise packages, addons, renderers, and core behavior in a context that resembles how users actually run Storybook. This matters because a monorepo change may compile correctly but still fail when linked into a concrete framework setup with stories, addons, and a running preview.

Sources: docs/contribute/code.mdx

Relevant Source Files

• docs/contribute/code.mdx — First-party contribution guide for code changes, including prerequisites, initial setup, sandbox startup, alternate sandbox templates, tests, branching, and interactive build workflow.

Contribution Paths

The public contribution area is organized around several kinds of work. Use the RFC process when the change is a feature request or design-level proposal that needs maintainer and community alignment before implementation. Use the code contribution path when you are fixing a bug or implementing an accepted change in the monorepo. Use the documentation path when the main artifact is reader-facing guidance, examples, or reference material. Use framework contribution guidance when the change is tied to a renderer or framework integration, because those changes often carry framework-specific assumptions and test expectations.

Reproduction work is also a valuable contribution path. A minimal reproduction gives maintainers a small, repeatable project that demonstrates a bug without requiring them to infer the failing setup from a full application. If you are not ready to propose or implement a fix, producing a clear reproduction can still shorten diagnosis time for maintainers and future contributors. For implementation work, however, start with the code contribution workflow below so that your local environment follows the same assumptions as the monorepo docs.

Prerequisites and Initial Setup

The code contribution guide starts with two environment assumptions: contributors should use Node 18, with v18.16.0 suggested, and Windows users should run commands from a terminal with administrator privileges. These prerequisites are not incidental. Storybook’s repository uses modern package-management and build tooling, and a mismatched Node runtime can cause failures before the actual code under development is reached. Treat the prerequisite check as part of the contribution, especially when triaging installation, builder, or test-runner issues.

Sources: docs/contribute/code.mdx

The first local step is to fork the Storybook monorepo, clone your fork, and enter the checkout. Storybook uses Yarn, and the guide directs contributors to enable Corepack so the repository can use the intended Yarn version. This creates a more reproducible setup across contributors because the package manager itself is controlled instead of depending on a globally installed Yarn binary that may behave differently.

Sources: docs/contribute/code.mdx

git clone https://github.com/your-username/storybook.git
cd storybook
corepack enable

Code Contribution Workflow

After setup, run the default sandbox before making changes. The documented command is yarn start, which installs required prerequisites, builds the code, creates and links a starter example based on a Vite React setup, and starts the Storybook server. This is the quickest smoke test for a fresh checkout because it exercises installation, compilation, sandbox generation, package linking, and the development server in one path. If the sandbox appears in the browser, you have a working baseline to compare against once you begin editing packages.

Sources: docs/contribute/code.mdx

yarn start

If your contribution targets a different renderer or user setup, use yarn task instead of relying on the default React Vite template. The task command prompts for your goals and then prints the full command with the selected options so it can be rerun. The guide also notes that yarn task takes development shortcuts, which can be surprising after switching branches. When the generated environment becomes stale, rerun the install and compile phases, or use the start-from=install flag to restart from the installation step without rediscovering the entire workflow manually.

Sources: docs/contribute/code.mdx

yarn task

Before changing code, run the test suite with yarn test. In this workflow, testing is not an afterthought at the end of the pull request; it is the check that confirms your local Storybook build is functional before you introduce new variables. If the baseline tests fail before your change, resolve the local environment issue first or capture it separately. Otherwise, later failures are harder to attribute to either your patch or the setup.

Sources: docs/contribute/code.mdx

yarn test

Interactive Development Loop

The recommended development loop uses two terminals. Keep the sandbox running in one terminal so you can see behavior in a real Storybook instance. In a second terminal, move into the code directory, create a branch, and run the build process. When prompted for watch mode, answer yes to develop interactively. Watch mode is especially useful when working on packages such as @storybook/addon-docs alongside the main storybook package, because changes can be rebuilt and reflected into the linked sandbox without restarting the entire workflow each time.

Sources: docs/contribute/code.mdx

git checkout -b my-first-storybook-contribution
yarn build

The guide calls out an important constraint of watch mode: for performance reasons, it only transpiles code and does not execute the TypeScript compiler. That means a change can appear to rebuild while still containing type errors that a stricter validation step would catch. Use watch mode for fast feedback while iterating, but do not treat it as the final correctness signal. Before opening or updating a pull request, rerun the relevant tests and any validation commands requested by maintainers for the package area you changed.

Sources: docs/contribute/code.mdx

System-to-Code Mapping

Next Steps

Choose the contribution path that matches the problem before you begin implementation. For a design-level feature, start with the RFC process. For unclear bugs, create or improve a reproduction. For code fixes, follow the local setup flow here, keep a sandbox running, and validate with tests before submitting. If your change affects docs, addons, builders, or framework integrations, read the related pages for those areas so that your pull request matches both the package contract and the reader-facing documentation expectations.