---
title: "Storybook Integration & Hosting"
sidebarTitle: "Storybook"
description: "Extract CSF component metadata, parse Storybook index versions (v2-v5), sync stories, and host static builds directly on deeepSpace for live previews."
keywords: "storybook component discovery, host storybook deeepspace, csf metadata sync"
icon: "book-open"
---

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`:

```bash
npm run 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.

<Note>
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.
</Note>

## 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`:

```json
{
  "discovery": {
    "type": "STORYBOOK",
    "storybookConfigDirectory": ".storybook",
    "storybookIndexJsonPath": "storybook-static/index.json",
    "componentIndexJsonPath": ".deeep.index.json",
    "stories": ["src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
    "exclude": ["**/node_modules/**", "**/dist/**"],
    "hostStorybook": true
  }
}
```

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.

<Warning>
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.
</Warning>

## 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.

```bash
deeep sync --no-storybook-hosting
```

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

```bash
deeep sync --storybook-hosting
```

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

| Setting or flag | Behavior |
| --- | --- |
| No flag, no `hostStorybook` | Hosting is off. |
| `hostStorybook: true`, no saved URL | Attempt hosting after sync. |
| `hostStorybook: true`, existing `storybookUrl` | Skip hosting to preserve the existing URL. |
| `--storybook-hosting` | Attempt hosting and override the existing-URL skip. |
| `--no-storybook-hosting` | Skip hosting for this run. |
| `--dry-run` | Never build or host, regardless of other flags. |

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.

<Note>
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.
</Note>

For unresolved stories, unsupported index versions, and source-analysis limits, see [Component index and sync data](/reference/component-index).