# Getting started

> Install StoryShelf, create a project, and review your first Storybook build in about ten minutes.

Source: https://storyshelf.js.org/guides/getting-started/

StoryShelf is a self-hosted visual testing platform for Storybook. You run one server, point your CI at it, and review pixel diffs in the browser.

![The projects overview: a card per project with its latest build and review backlog](https://storyshelf.js.org/_astro/projects-list-light.BLu6iGeZ_Z2wrNf6.webp)

You need a Storybook with a `.storybook/main.*` file, and Node.js 24 or later on the machine that will run the server.

## 1. Scaffold a server

Use the CLI to scaffold a new server project:

```sh
npx storyshelf server init
```

It asks for a project name and directory, then which database (SQLite by default), storage (local filesystem by default), auth (none by default), and git provider (GitHub, GitLab, or none). It generates `src/index.ts`, a `package.json` with the matching adapters and a `tsconfig.json` for your editor.

## 2. Start the server

```sh
cd my-storyshelf
npm install
npm start
```

The server listens on `http://localhost:3000`.

## 3. Initialize Storybook and create a project

Initialize the client config and create a project. Creating a project needs a site-admin token when auth is enabled.

Write `.storybook/storyshelf.json` (prompts for anything you leave out):

```sh
npx storyshelf init --url http://localhost:3000 --slug my-design-system
```

Or create the project on the server and write the config in one step:

```sh
npx storyshelf create --url http://localhost:3000 --name "My Design System" --token $STORYSHELF_ADMIN_TOKEN
```

`create` prints the project slug and a CI token, and writes `.storybook/storyshelf.json`.

> **Caution:**
>
> Keep the CI token secret: set it as `STORYSHELF_TOKEN` in your CI environment. `create` and `init` fail if `.storybook/main.*` is not found.

## 4. Upload a build from CI

With `.storybook/storyshelf.json` present, `upload` flags can be omitted, and running `storyshelf` with no command defaults to `upload`:

```sh
npx storyshelf upload --token shelf_xxx --sha "$GITHUB_SHA" --branch "$GITHUB_REF_NAME"
```

Or, when the config file and environment are in place, simply:

```sh
npx storyshelf
```

Explicit flags always work too:

```sh
npx storyshelf upload --url http://localhost:3000 --slug my-design-system --token shelf_xxx --sha "$GITHUB_SHA" --branch "$GITHUB_REF_NAME"
```

StoryShelf renders every story server-side and diffs it against the branch baseline. Without `.storybook/storyshelf.json`, running `storyshelf` just shows help pointing you to `init`.

For a complete pipeline, see [CI setup](https://storyshelf.js.org/guides/ci/).

## 5. Review

Open the project in your browser. A build that needs attention shows **N to review** on its project card; open it, and choose **Review diffs** for the review workspace: a filmstrip of changed stories, baseline, current and diff side by side (or swiped, blended or flipped), and **Approve** / **Reject** with the keyboard.

![The review workspace: snapshot filmstrip, baseline | current | diff comparison, and the action bar](https://storyshelf.js.org/_astro/diff-review-light.8DfXbczT_ZxVxdf.webp)

When every change is decided, the build’s status check goes green and you can merge.

## Next steps

- [Review workflow](https://storyshelf.js.org/guides/review/): comparison modes, shortcuts, and bulk actions.
- [CI setup](https://storyshelf.js.org/guides/ci/) and the [merge gate](https://storyshelf.js.org/guides/merge-gate/): make the check required.
- [Project settings](https://storyshelf.js.org/guides/project-settings/): thresholds, viewports, labels, members and tokens.
- [Deployment](https://storyshelf.js.org/guides/deployment/): take the server beyond localhost.