Set Up a Project

Purpose and Scope

This page explains what happens after Storybook has been installed and the first project files exist. The setup task is not only to start a server; it is to prove that one real component can render in isolation, then adjust configuration until the component looks and behaves as it does in the application. Storybook’s setup guide frames this as the next step after learning what stories are and how to browse them: pick a simple component, add a story file beside it, open Storybook, and then resolve any stack-specific differences that appear. Sources: docs/get-started/setup.mdx

A useful setup mindset is to treat Storybook as a separate rendering environment for the same components your app already uses. It renders the DOM you provide, but it does not automatically know every styling convention, provider tree, build transform, or runtime assumption in your application. That separation is the point: it makes component states easier to inspect, test, and document. It also means the first run can reveal missing CSS, missing providers, or build settings that your application normally supplies implicitly. Sources: docs/get-started/setup.mdx

Relevant Source Files

• docs/get-started/setup.mdx - Reader-facing setup flow: create a story for a simple component, view it in Storybook, then configure styles, build settings, runtime behavior, and component context as needed.
• code/addons/onboarding/README.md - Documents the onboarding addon that can appear during first-time setup, including how to trigger it later and how to uninstall it after the guided tour is complete.
• code/.storybook/main.ts - Repository-local Storybook configuration example showing real stories, addons, previewAnnotations, build, and framework settings for the Storybook monorepo itself.

Core Setup Flow

Start with a deliberately small component, such as a button, because the goal is to validate the Storybook environment before modeling a large screen or application route. The setup guide recommends creating a story file with one of the common story filename extensions and placing it alongside the component. Once the story exists, open the running Storybook and inspect the rendered component. At this stage, an unusual appearance is not automatically a failure; it is a signal that the isolated environment still needs styling, build, runtime, or context configuration. Sources: docs/get-started/setup.mdx

The first story is also a diagnostic tool. If Storybook starts and the component appears, then discovery, compilation, and rendering are at least partially working. If the command-line process reports errors while running the development server, the guide points readers toward build configuration such as presets, Babel, or Webpack. If the build succeeds but the browser fails immediately, the issue is more likely runtime compilation or browser interpretation. If only one story fails, the component probably expects a provider or parent context that the isolated canvas has not yet received. Sources: docs/get-started/setup.mdx

yarn storybook

Generated Configuration and Story Discovery

A generated Storybook project normally has a configuration file under the project’s Storybook directory. The repository’s own configuration demonstrates the shape of that file using defineMain from the React Vite integration. It declares many story locations, including simple glob patterns and object entries with directories, title prefixes, and file filters. That illustrates the general contract: Storybook needs to know where stories live and how they should be grouped in the sidebar before the development UI can present a useful navigation tree. Sources: code/.storybook/main.ts

The same configuration example shows that setup is additive. The addons list includes onboarding, themes, docs, designs, Vitest, accessibility, MCP, pseudo states, Chromatic, and a local services preset. A new application will usually start with fewer entries, but the pattern is the same: each addon is registered in configuration so Storybook can extend the manager UI, preview behavior, documentation, testing, or integration surface. The example also includes preview annotations and a framework declaration, showing that setup connects story discovery, runtime preview behavior, and the selected framework package in one main configuration object. Sources: code/.storybook/main.ts

Onboarding Experience

During first-time setup, Storybook may prompt the developer to enable the onboarding addon. The addon is a guided tour of Storybook basics and is specifically meant to help new users learn core features and story-writing patterns. If a team skips the prompt, the README explains that the tour can still be triggered manually later, as long as the default example stories remain. Navigating to the onboarding route on the local server starts the experience, which makes it useful for developers who join a project after the initial installation. Sources: code/addons/onboarding/README.md

http://localhost:6006/?path=/onboarding

The onboarding addon is intentionally temporary. Its README says it is not needed after the guided experience is complete and will not activate unless manually triggered. Removing it has two parts: uninstall the package with the project’s package manager, and remove the addon entry from the Storybook main configuration. This keeps long-lived project configuration focused on capabilities the team actually uses, while still allowing the first-run experience to be friendly for people who are learning Storybook. Sources: code/addons/onboarding/README.md

yarn remove @storybook/addon-onboarding
npm uninstall -D @storybook/addon-onboarding
pnpm remove -D @storybook/addon-onboarding

Styling, Build, Runtime, and Context Checks

Styling is often the first visible setup gap. The setup guide emphasizes that Storybook is not opinionated about how CSS is generated or loaded. It renders the DOM elements provided by stories, but application-specific styling pipelines may require additional configuration. The guide points readers toward recipes for common tools such as Tailwind, Material UI, Vuetify, Styled Components, Emotion, Sass, Bootstrap, Less, and Vanilla Extract, and then toward the broader styling and CSS configuration page if their tool is not listed. Sources: docs/get-started/setup.mdx

Build and runtime checks are separate but related. Build failures usually appear in the terminal while the Storybook command runs, and the guide suggests presets, Babel configuration, or Webpack adjustments as common remedies. Runtime failures appear after the browser connects to the built Storybook and often mean that an input file did not compile or transpile into code the browser can interpret. For a team setting up a project, this distinction helps route the investigation: terminal errors point toward builder configuration, while browser-only failures point toward runtime compatibility or transforms. Sources: docs/get-started/setup.mdx

Component context is the final common setup category. Many components assume a theme provider, router, store, internationalization layer, or other parent context exists above them. In Storybook, that context must be provided explicitly. The setup guide directs React-like renderers to use decorators when stories need wrappers, and it names the preview configuration file as the place to customize how components render in the canvas preview iframe. This is the main bridge between isolated stories and application-level assumptions that components were originally written against. Sources: docs/get-started/setup.mdx

First-Run Checklist

Use the first development-server session to answer a small set of concrete questions. Can Storybook discover the new story file? Does the component render at all? Are styles loaded? Does the browser console show runtime failures? Does the component require a provider or other context wrapper? Do addons shown in the UI match the entries configured for the project? The repository configuration demonstrates that story discovery, addon registration, preview annotations, build options, and framework selection all participate in the final first-run experience. Sources: docs/get-started/setup.mdx, code/.storybook/main.ts

A practical next step is to keep the first story simple, fix the environment until it matches the application’s assumptions, and only then expand to additional component states. If onboarding is enabled, complete the tour and remove the addon when the team no longer needs it. After that, continue with pages about Component Story Format, decorators, styling and static assets, framework-specific setup, and addon configuration. Those topics map directly to the setup issues surfaced by the first run: story shape, wrapper context, asset loading, framework behavior, and optional project capabilities. Sources: docs/get-started/setup.mdx, code/addons/onboarding/README.md, code/.storybook/main.ts