Storybook Deployment Guide

Complete guide for deploying the Storybook component library to storybook.ourlantern.app and storybook.dev.ourlantern.app.

Overview

The Storybook site is separate from the main Lantern app and documentation, with its own deployment pipeline:

Component	Production	Development
Main App	`ourlantern.app`	`dev.ourlantern.app`
Docs Site	`docs.ourlantern.app`	`docs.dev.ourlantern.app`
Storybook	`storybook.ourlantern.app`	`storybook.dev.ourlantern.app`

Key Benefits:

Stakeholders can view and interact with components without local setup
Designers can review component variations and documentation
Developers can share component examples via URLs
Independent deployment from main app
Automatic preview URLs for component changes

Deployment Flow

Push to GitHub (main or dev branch)
    ↓
Cloudflare Pages Git Integration
    ↓
Build static Storybook (npm run build-storybook)
    ↓
Deploy to Cloudflare Pages
    ↓
Available at storybook.ourlantern.app (main) or storybook.dev.ourlantern.app (dev)

Automatic Deployments

main branch → storybook.ourlantern.app (production)
dev branch → storybook.dev.ourlantern.app (development)
feature branches → Preview URLs (e.g., feature-xyz.lantern-storybook-dev.pages.dev)

Quick Start

Local Development

bash

# Start the Storybook dev server
npm run storybook

# Build Storybook for production (static site)
npm run build-storybook

# Preview the production build
npx http-server storybook-static

The dev server runs on http://localhost:6006 by default.

Initial Setup in Cloudflare

Step 1: Create Production Storybook Project

Go to Cloudflare Dashboard → Pages
Click "Create a project" → "Connect to Git"
Select cattreedev/lantern_app repository
Configure:
- Project name: lantern-storybook
- Production branch: main
- Build command: npm run build-storybook
- Build output directory: storybook-static
- Root directory: (leave empty)
Click "Save and Deploy"

Step 2: Create Development Storybook Project

Click "Create a project" again
Select same repo cattreedev/lantern_app
Configure:
- Project name: lantern-storybook-dev
- Production branch: dev (not main!)
- Build command: npm run build-storybook
- Build output directory: storybook-static
- Root directory: (leave empty)
Click "Save and Deploy"

Step 3: Add Custom Domains

Production Storybook

In lantern-storybook project, go to Custom domains
Click Set up a custom domain
Enter storybook.ourlantern.app
Cloudflare will auto-create the required DNS records

Development Storybook

In lantern-storybook-dev project, go to Custom domains
Click Set up a custom domain
Enter storybook.dev.ourlantern.app
Cloudflare will auto-create the required DNS records

Step 4: Verify DNS Configuration

In Cloudflare dashboard, DNS tab should show:

CNAME  storybook      → lantern-storybook.pages.dev        (Proxied)
CNAME  storybook.dev  → lantern-storybook-dev.pages.dev    (Proxied)

Note: These are in addition to your existing DNS records:

CNAME  @              → lantern-app.pages.dev              (Proxied)
CNAME  dev            → lantern-app-dev.pages.dev          (Proxied)
CNAME  docs           → lantern-docs.pages.dev             (Proxied)
CNAME  docs.dev       → lantern-docs-dev.pages.dev         (Proxied)

Deployment Workflow

Updating Storybook

1. Make Changes

bash

# Create a feature branch
git checkout -b feature/update-button-story dev

# Add or update stories
# Stories are in src/**/*.stories.jsx

# Test locally
npm run storybook

2. Preview Changes

bash

# Build static Storybook
npm run build-storybook

# Verify the build
ls -la storybook-static/

# Optional: preview locally
npx http-server storybook-static

3. Push to GitHub

bash

git add .
git commit -m "Add button variants to Storybook"
git push origin feature/update-button-story

Result: Cloudflare creates a preview URL automatically:

https://feature-update-button-story.lantern-storybook-dev.pages.dev
Share this URL with stakeholders for review!

4. Merge to Dev

After review:

bash

git checkout dev
git merge feature/update-button-story
git push origin dev

Result: Deploys to https://storybook.dev.ourlantern.app

5. Deploy to Production

When ready for production:

bash

git checkout main
git merge dev
git push origin main

Result: Deploys to https://storybook.ourlantern.app

Managing Access (Optional)

Public Access (Recommended for Stakeholders)

By default, Storybook sites are public. This is ideal for:

Sharing with designers and product managers
External stakeholder reviews
Component library documentation

Restricted Access (If Needed)

If you need to restrict access:

Go to Cloudflare Zero Trust → Access → Applications
Click Add an application → Self-hosted
Configure:
- Application name: lantern-storybook
- Domain: storybook.ourlantern.app
- Policy: Choose authentication method (PIN, email, etc.)
Repeat for dev environment if needed

Note: For stakeholder access, keeping it public is usually better.

Using Storybook for Reviews

Direct links to components:

https://storybook.ourlantern.app/?path=/story/components-button--default

Canvas mode (component only):

https://storybook.ourlantern.app/iframe.html?id=components-button--default

Docs mode (with documentation):

https://storybook.ourlantern.app/?path=/docs/components-button--docs

Preview URLs for Feature Branches

Every feature branch gets a preview URL:

https://[branch-name].lantern-storybook-dev.pages.dev

Share these URLs in:

Pull request descriptions
Slack/email for design reviews
Jira/Linear tickets
Design handoff documents

Troubleshooting

Build Fails in Cloudflare

Check the build logs:

Go to Cloudflare Dashboard → Pages → your project
Click on the failed deployment
View the build log

Common issues:

Missing dependencies: Check package.json has all Storybook packages
Build command wrong: Should be npm run build-storybook
Output directory wrong: Should be storybook-static

Storybook Shows Blank Page

Possible causes:

Base path misconfiguration
Missing static assets
Build didn't complete successfully

Fix:

Build locally: npm run build-storybook
Check storybook-static/ has files
Look for JavaScript errors in browser console

Stories Not Updating

Ensure you're looking at the right environment:

Production (main branch): storybook.ourlantern.app
Development (dev branch): storybook.dev.ourlantern.app
Feature branch: [branch-name].lantern-storybook-dev.pages.dev

Force a rebuild:

Go to Cloudflare Pages → Deployments
Click "Retry deployment" on the latest build

Custom Domain Not Working

Check DNS records:

bash

nslookup storybook.ourlantern.app
# Should resolve to lantern-storybook.pages.dev

If not resolving:

Go to Cloudflare Dashboard → DNS
Verify CNAME record exists and is proxied (orange cloud)
Wait 5-10 minutes for DNS propagation

Build Configuration

Wrangler Config

The wrangler.storybook.toml file defines the build configuration:

toml

name = "lantern-storybook"
compatibility_date = "2026-01-03"

[pages]
  build_command = "npm run build-storybook"
  build_output_directory = "storybook-static"
  node_version = "20"

Package.json Scripts

json

{
  "scripts": {
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build"
  }
}

Best Practices

Development Workflow

Always test locally first: npm run storybook
Build before pushing: npm run build-storybook to catch build errors
Use feature branches: Get preview URLs for reviews
Merge to dev first: Test on dev environment before production
Keep stories updated: Add stories for new components immediately

Stakeholder Communication

Share preview URLs early: Get feedback during development
Use descriptive branch names: Makes preview URLs clearer
Add documentation to stories: Use MDX or description fields
Group related components: Use consistent naming in story titles

Performance

Optimize images: Use compressed images in stories
Lazy load large components: Use code splitting if needed
Monitor build times: Keep builds under 5 minutes

DEPLOYMENT.md — Main app deployment guide
DOCS_DEPLOYMENT.md — Documentation site deployment
SUBDOMAINS_AND_ACCESS.md — DNS and access management
docs/storybook/STORYBOOK.md — Storybook usage guide
docs/storybook/ADDING_STORIES.md — How to add new stories

Quick Reference

URLs

Environment	URL
Production Storybook	`https://storybook.ourlantern.app`
Dev Storybook	`https://storybook.dev.ourlantern.app`
Preview (feature branch)	`https://[branch-name].lantern-storybook-dev.pages.dev`

Commands

bash

# Local development
npm run storybook

# Build static site
npm run build-storybook

# Preview build
npx http-server storybook-static

# Push and deploy
git push origin [branch-name]

Cloudflare Projects

Production: lantern-storybook (main branch → storybook.ourlantern.app)
Development: lantern-storybook-dev (dev branch → storybook.dev.ourlantern.app)

Storybook Deployment Guide ​

Overview ​

Deployment Flow ​

Automatic Deployments ​

Quick Start ​

Local Development ​

Initial Setup in Cloudflare ​

Step 1: Create Production Storybook Project ​

Step 2: Create Development Storybook Project ​

Step 3: Add Custom Domains ​

Production Storybook ​

Development Storybook ​

Step 4: Verify DNS Configuration ​

Deployment Workflow ​

Updating Storybook ​

1. Make Changes ​

2. Preview Changes ​

3. Push to GitHub ​

4. Merge to Dev ​

5. Deploy to Production ​

Managing Access (Optional) ​

Public Access (Recommended for Stakeholders) ​

Restricted Access (If Needed) ​

Using Storybook for Reviews ​

Sharing Components with Stakeholders ​

Preview URLs for Feature Branches ​

Troubleshooting ​

Build Fails in Cloudflare ​

Storybook Shows Blank Page ​

Stories Not Updating ​

Custom Domain Not Working ​

Build Configuration ​

Wrangler Config ​

Package.json Scripts ​

Best Practices ​

Development Workflow ​

Stakeholder Communication ​

Performance ​

Related Documentation ​

Quick Reference ​

URLs ​

Commands ​

Cloudflare Projects ​

Storybook Deployment Guide

Overview

Deployment Flow

Automatic Deployments

Quick Start

Local Development

Initial Setup in Cloudflare

Step 1: Create Production Storybook Project

Step 2: Create Development Storybook Project

Step 3: Add Custom Domains

Production Storybook

Development Storybook

Step 4: Verify DNS Configuration

Deployment Workflow

Updating Storybook

1. Make Changes

2. Preview Changes

3. Push to GitHub

4. Merge to Dev

5. Deploy to Production

Managing Access (Optional)

Public Access (Recommended for Stakeholders)

Restricted Access (If Needed)

Using Storybook for Reviews

Sharing Components with Stakeholders

Preview URLs for Feature Branches

Troubleshooting

Build Fails in Cloudflare

Storybook Shows Blank Page

Stories Not Updating

Custom Domain Not Working

Build Configuration

Wrangler Config

Package.json Scripts

Best Practices

Development Workflow

Stakeholder Communication

Performance

Related Documentation

Quick Reference

URLs

Commands

Cloudflare Projects