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

# 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

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

Step 2: Create Development Storybook Project

1. Click "Create a project" again
2. Select same repo cattreedev/lantern_app
3. 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)
4. Click "Save and Deploy"

Step 3: Add Custom Domains

Production Storybook

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

Development Storybook

1. In lantern-storybook-dev project, go to Custom domains
2. Click Set up a custom domain
3. Enter storybook.dev.ourlantern.app
4. 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

# 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

# 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

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:

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:

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:

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

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

---

Using Storybook for Reviews

Sharing Components with Stakeholders

1. Direct links to components:

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

2. Canvas mode (component only):

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

3. 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:

1. Go to Cloudflare Dashboard → Pages → your project
2. Click on the failed deployment
3. 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:

1. Build locally: npm run build-storybook
2. Check storybook-static/ has files
3. 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:

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

Custom Domain Not Working

Check DNS records:

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

If not resolving:

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

---

Build Configuration

Wrangler Config

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

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

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

---

Best Practices

Development Workflow

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

Stakeholder Communication

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

Performance

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

---

Related Documentation

• 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

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