Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Storybook

Storybook is a tool for developing and testing UI components in isolation. It provides a sandboxed environment where you can build, view, and test components without running the full Electron application.

Starting Storybook

1
make storybook
2
# or
3
bun run storybook

This will start the Storybook development server at http://localhost:6006.

Building Static Storybook

To build a static version of Storybook that can be deployed:

1
make storybook-build
2
# or
3
bun run storybook:build

The output will be in storybook-static/.

Writing Stories

Stories are colocated with their components. For example, ErrorMessage.tsx has its stories in ErrorMessage.stories.tsx in the same directory.

Basic Story Structure

1
import type { Meta, StoryObj } from "@storybook/react";
2
import { MyComponent } from "./MyComponent";
3
4
const meta = {
5
title: "Components/MyComponent",
6
component: MyComponent,
7
parameters: {
8
layout: "centered", // or "fullscreen" or "padded"
9
},
10
tags: ["autodocs"], // Enables automatic documentation
11
} satisfies Meta<typeof MyComponent>;
12
13
export default meta;
14
type Story = StoryObj<typeof meta>;
15
16
export const Default: Story = {
17
args: {
18
prop1: "value1",
19
prop2: "value2",
20
},
21
};
22
23
export const Variant: Story = {
24
args: {
25
prop1: "different value",
26
prop2: "another value",
27
},
28
};

Component Examples

See the existing stories for reference:

  • src/components/ErrorMessage.stories.tsx - Simple component with multiple states
  • src/components/Modal.stories.tsx - Complex component with children and multiple variants

Global Styles

Storybook automatically applies the same global styles as the main app:

  • Color variables (GlobalColors)
  • Font definitions (GlobalFonts)
  • Scrollbar styles (GlobalScrollbars)

These are configured in .storybook/preview.tsx.

Handling Electron APIs

Some components depend on window.api for Electron IPC communication. For these components:

  1. Preferred: Extract the component logic to accept props instead of calling IPC directly
  2. Alternative: Mock the window.api object in .storybook/preview.tsx

Example mock structure:

1
window.api = {
2
workspace: {
3
create: async () => ({ success: true, metadata: { ... } }),
4
list: async () => ({ success: true, workspaces: [...] }),
5
// ...
6
},
7
// ... other IPC channels
8
};

Benefits

  • Isolated Development: Build components without running the full Electron app
  • Visual Testing: See all component states at once
  • Documentation: Stories serve as living documentation with autodocs
  • Faster Iteration: Hot reload is faster than Electron rebuilds
  • Accessibility: Storybook addons can check accessibility issues

Configuration

  • .storybook/main.ts - Main Storybook configuration
  • .storybook/preview.tsx - Global decorators and parameters
  • tsconfig.json - Includes .storybook/**/*.ts for type checking

Tips

  • Keep stories simple and focused on visual states
  • Use Storybook's Controls addon to make props interactive
  • Add multiple stories for different states (loading, error, success, etc.)
  • Use the tags: ["autodocs"] option to generate automatic documentation