contributing/development

9 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Sandboxes in Storybook development

Storybook development happens in sandboxes, which are templated Storybook environments corresponding to different user setups. Each sandbox has generalized stories injected to test core features and addons across various environments.

Start first Storybook sandbox locally

To run a sandbox locally, use the `yarn start` command. It will install required prerequisites, build the code, create and link a starter example based on a Vite React setup, and start the Storybook server. By default, this initializes a Vite-based React template.

Running different sandbox templates with yarn task

To run a different sandbox template instead of the default Vite React setup, run `yarn task` and answer the prompted questions accurately. The command will show the full command with selected options for future reference. Using the `start-from=install` flag can speed up the process when switching branches by re-running both the install and compile tasks.

Starting development workflow in Storybook

To start developing: run a sandbox in one terminal window and the interactive build process in a separate terminal. Create a new branch with `git checkout -b my-first-storybook-contribution`, then run `yarn build`. When prompted to start in watch mode, answer yes to develop interactively. Then choose which packages to build, for example both `@storybook/addon-docs` and `storybook`.

Build watch mode limitations

Build watch mode is useful for interactive development but only transpiles code and does not execute the TypeScript compiler for performance reasons. If something isn't working as expected, run the build command without watch mode to re-generate TypeScript types and perform automatic type checking.

Preview vs Manager refresh behavior in Storybook development

If work affects the Preview (the innermost Storybook iframe where stories are displayed), it automatically refreshes one to two seconds after saving. If work affects the Manager (the outermost Storybook iframe where addons are displayed), manual refresh is required after saving.

yarn build command arguments

The `yarn build` command accepts the following arguments: `--all` builds all packages; `--watch` enables watch mode and skips the prompt; `--prod` builds for production and skips the production mode prompt; individual package names can be passed without the `@storybook/` prefix, e.g., `storybook`, `addon-docs`. Example: `yarn build --watch storybook addon-docs` builds Storybook and the docs addon in watch mode.

yarn build --all --watch resource requirements

Using `yarn build --all --watch` watches all packages but is resource-intensive and troublesome when packages to change are unknown ahead of time. It can be highly demanding even on modern machines, so selectively watching only necessary packages is recommended.

Storybook requires at least one local story or docs page

Storybook does not work unless at least one local story (or docs page) is defined in the project. A local story is a .stories.* or .mdx file that is referenced in .storybook/main.js config.

Give your agent this brain