Storybook discovery joins your generated story index with local component and story source files. You can use an existing deployed Storybook URL or publish a static build through deeepSpace.

​
Prepare your Storybook

Install your project’s dependencies and build Storybook using the script already defined in its package.json. For example, if your script is named build-storybook:
Find the generated index.json (commonly storybook-static/index.json). Legacy story indexes with a stories collection are also supported. Commit and push the component sources, their dependencies and styles, and the story files before syncing. The generated Storybook output does not need to be committed.
Component sync runs before hosting. Even deeep sync --storybook-hosting needs a usable local index first when discovery is STORYBOOK. Hosting cannot bootstrap a sync blocked by a missing or empty index.

​
Connect Storybook discovery

Run deeep init for a new setup, or deeep init --force to change an existing one. Choose Storybook and review:
  • The Storybook configuration directory.
  • The generated index path.
  • Story patterns and the deeep component index output path.
  • An optional deployed Storybook URL for live previews and deep links.
  • Whether to host Storybook on deeep during sync (off by default).
The CLI discovers Storybook configuration directories and index files, and can infer output paths from package scripts and supported wrapper scripts. You can enter a path manually if detection is incorrect. If Storybook is not detected, initialization shows setup instructions and stops that selection. This example is the discovery section of an initialized deeep.json:
All file paths are relative to the Git repository root. In a monorepo, use paths such as packages/ui/.storybook and packages/ui/storybook-static/index.json. Run deeep from the repository root containing deeep.json. Storybook import paths are resolved against the package owning the configuration first, then the repository root.
The generated Storybook index determines which stories are processed. The saved stories and exclude fields are metadata in the current implementation; they do not filter the Storybook index. Change your Storybook configuration and rebuild its index to change the synced story set.

​
Use an existing deployed Storybook

Set discovery.storybookUrl to your deployment’s base URL, for example https://storybook.example.com. It must start with http:// or https://; trailing slashes are removed in the sync manifest.
The URL accompanies Storybook discovery metadata. It does not replace the local index or local story source files, and the CLI does not download the remote index.

​
Host Storybook on deeep

After component sync succeeds, the CLI finds a package script containing storybook build, build-storybook, or a recognized wrapper. It runs the build in that package, uploads the output files, updates the project’s storybookUrl setting, and saves the public URL in discovery.storybookUrl locally. Build output is inferred from explicit --output-dir / -o options, supported outDir configuration or wrapper patterns, then defaults to storybook-static in the build package. Script and configuration parsing is heuristic; verify the chosen command and directory in custom setups. For monorepos, the CLI considers nested packages and makes ancestor node_modules/.bin directories available. Yarn Plug’n’Play builds run through yarn run.

​
Hosting precedence and republishing

After the first successful publish saves a URL, use --storybook-hosting to republish changes. Setting hostStorybook: true alone does not rebuild on every sync. deeep init can save the hosting preference but does not run the hosting pipeline. Hosting is also available after CLI discovery when your repository has a discoverable Storybook build script. The flags do not change your discovery mode.

​
Limits and recovery

  • The build timeout defaults to 600 seconds. Set DEEEP_STORYBOOK_BUILD_TIMEOUT to change it.
  • If a build command is missing and Storybook is declared in the repository, an interactive terminal offers to install dependencies and retry once. It detects npm, pnpm, Yarn, or Bun from the nearest lockfile. Noninteractive runs show instructions instead.
  • Dependency installation defaults to a 1,800-second timeout, configurable with DEEEP_STORYBOOK_INSTALL_TIMEOUT.
  • More than 5,000 output files stops publishing. Output larger than 500 MiB produces a warning but still uploads. File symlinks are skipped.
  • Uploads retry network failures and server errors; HTTP 4xx failures are reported without retry. Error output includes affected paths and response details.
  • No recognized build script or an empty output directory skips hosting. A missing output directory or failed upload reports a hosting failure.
  • If the server reports missing index.html, check that the detected output directory contains the complete static site.
Hosting uploads the static build to a public URL, including assets and any source maps your build produces. Review the output you intend to publish. A hosting failure leaves the earlier component sync intact.
For unresolved stories, unsupported index versions, and source-analysis limits, see Component index and sync data.