Lantern

Appearance

Storybook Website Setup — Quick Start Guide ​

Goal: Make Storybook viewable by stakeholders at storybook.ourlantern.app and storybook.dev.ourlantern.app

Estimated time: 15-20 minutes

What You Need ​

✅ Access to Cloudflare Dashboard
✅ Access to cattreedev/lantern_app GitHub repository
✅ This guide (you're reading it!)

Overview ​

Storybook is already built into the codebase. It just needs to be deployed to Cloudflare Pages similar to how the docs site is deployed.

What Cloudflare will do:

  • Detect when you push to main or dev branches
  • Automatically run npm run build-storybook
  • Deploy the static site to your custom domains
  • Create preview URLs for feature branches

Step-by-Step Setup ​

Step 1: Create Production Storybook Project ​

  1. Go to Cloudflare Pages:

  2. Connect to Git:

    • Click Connect to Git
    • Select GitHub
    • Choose cattreedev/lantern_app repository

  3. Configure the project:

    Project name:              lantern-storybook
Production branch:         main
Build command:             npm run build-storybook
Build output directory:    storybook-static
Root directory:            (leave empty)

  4. Advanced settings (expand if needed):

    Node version:              20
Environment variables:     (none needed)

  5. Click "Save and Deploy"

    The first build will start automatically. It will take 2-3 minutes.

  6. Wait for success:

    • You'll see "Success! Your site is live!"
    • Default URL: lantern-storybook.pages.dev
    • Test it to make sure Storybook loads

Step 2: Add Custom Domain (Production) ​

  1. In the lantern-storybook project:

    • Go to Custom domains tab
    • Click Set up a custom domain

  2. Enter domain:

    storybook.ourlantern.app

  3. DNS configuration:

    • Cloudflare will automatically create a CNAME record
    • It should show: CNAME storybook → lantern-storybook.pages.dev (Proxied)
    • Click Activate domain

  4. Verify:

Step 3: Create Development Storybook Project ​

Now repeat the process for the dev environment.

  1. Go back to Cloudflare Pages:

    • Click Create a project again
    • Click Connect to Git
    • Select cattreedev/lantern_app (same repository)

  2. Configure the dev project:

    Project name:              lantern-storybook-dev
Production branch:         dev          ⚠️ NOTE: dev, not main!
Build command:             npm run build-storybook
Build output directory:    storybook-static
Root directory:            (leave empty)

  3. Click "Save and Deploy"

  4. Wait for build to complete

Step 4: Add Custom Domain (Development) ​

  1. In the lantern-storybook-dev project:

    • Go to Custom domains tab
    • Click Set up a custom domain

  2. Enter domain:

    storybook.dev.ourlantern.app

  3. Activate and verify:

Step 5: Verify DNS Records ​

  1. Go to DNS tab in Cloudflare dashboard

  2. You should see these new records:

    Type   Name            Content                              Proxy
CNAME  storybook       lantern-storybook.pages.dev         Proxied (orange)
CNAME  storybook.dev   lantern-storybook-dev.pages.dev     Proxied (orange)

  3. Along with existing 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

Testing the Deployment ​

Test Production ​

  1. Go to https://storybook.ourlantern.app
  2. You should see:
    • Storybook UI with sidebar navigation
    • "Components" section with buttons, badges, etc.
    • "Screens" section with dashboard, profile, etc.
    • "Style" section with colors and icons

Test Development ​

  1. Go to https://storybook.dev.ourlantern.app
  2. Should look similar to production
  3. May have newer/experimental components

Test Preview URLs ​

  1. Create a test branch:

    bash
    git checkout -b test/storybook-preview dev
git push origin test/storybook-preview

  2. Cloudflare will create a preview URL:

    https://test-storybook-preview.lantern-storybook-dev.pages.dev

  3. You can find it in:

    • Cloudflare Pages → lantern-storybook-dev → Deployments
    • GitHub pull request (if you create one)

Access Control (Optional) ​

By default, Storybook is public (no login required). This is recommended for stakeholder access.

If you need to restrict access:

  1. Go to Cloudflare Zero Trust:

    • Dashboard → Zero Trust → Access → Applications
    • Click Add an application → Self-hosted

  2. Configure:

    Application name:    lantern-storybook
Domain:              storybook.ourlantern.app
Policy:              One-time PIN (or choose another method)

  3. Repeat for dev if needed:

    Application name:    lantern-storybook-dev
Domain:              storybook.dev.ourlantern.app

Recommendation: Keep it public for easier stakeholder access.

Automatic Deployments ​

Once set up, deployments are automatic:

ActionResult
Push to mainDeploys to storybook.ourlantern.app
Push to devDeploys to storybook.dev.ourlantern.app
Push to feature branchCreates preview URL: [branch-name].lantern-storybook-dev.pages.dev

No manual steps needed! Just push code and Cloudflare handles the rest.

Sharing with Stakeholders ​

Share the URLs ​

Send these links to designers, PMs, and stakeholders:

Production (stable):

https://storybook.ourlantern.app

Development (latest):

https://storybook.dev.ourlantern.app

Share the Guide ​

Point stakeholders to the guide:

docs/storybook/STAKEHOLDER_GUIDE.md

It explains:

  • How to navigate Storybook
  • How to interact with components
  • How to share specific component links
  • Common use cases for designers and PMs

Troubleshooting ​

Build Fails ​

Check the build logs:

  1. Cloudflare Pages → your project → Deployments
  2. Click the failed deployment
  3. Read the build log

Common issues:

  • Node version mismatch (should be 20)
  • Missing dependencies (run npm install locally to verify)
  • Build command wrong (should be npm run build-storybook)

Custom Domain Not Working ​

Check DNS:

  1. Go to DNS tab in Cloudflare
  2. Verify CNAME record exists
  3. Make sure it's Proxied (orange cloud)

Wait for propagation:

  • DNS usually propagates in 1-2 minutes
  • Can take up to 10 minutes in rare cases

Test with nslookup:

bash
nslookup storybook.ourlantern.app
# Should resolve to Cloudflare IP

Storybook Looks Broken ​

Check the build:

  1. Build locally: npm run build-storybook
  2. Verify storybook-static/ directory exists
  3. Check for errors in the build output

Check browser console:

  1. Open browser DevTools (F12)
  2. Look for JavaScript errors
  3. Check if assets are loading (Network tab)

Verification Checklist ​

Once setup is complete, verify:

  • [ ] Production URL works: storybook.ourlantern.app
  • [ ] Dev URL works: storybook.dev.ourlantern.app
  • [ ] Components are visible in sidebar
  • [ ] Controls panel works (can change component props)
  • [ ] Docs tab loads for components
  • [ ] Preview URLs work for feature branches
  • [ ] DNS records are correct in Cloudflare
  • [ ] Build logs show no errors

Next Steps ​

  1. Share with team:

    • Post URLs in Slack
    • Update team wiki/docs
    • Share STAKEHOLDER_GUIDE.md with non-technical users

  2. Monitor:

    • Check Cloudflare Pages dashboard for failed builds
    • Review deployments regularly

  3. Optimize (future):

    • Consider adding Chromatic for visual regression testing
    • Add more stories for key components
    • Set up access control if needed

Reference Documentation ​

  • Full deployment guide: docs/engineering/deployment/STORYBOOK_DEPLOYMENT.md
  • Stakeholder guide: docs/storybook/STAKEHOLDER_GUIDE.md
  • Main deployment docs: docs/engineering/deployment/DEPLOYMENT.md
  • DNS and subdomains: docs/engineering/deployment/SUBDOMAINS_AND_ACCESS.md

Summary ​

What you did:

  1. Created two Cloudflare Pages projects (prod and dev)
  2. Connected them to GitHub repository
  3. Added custom domains
  4. Verified deployments work

What happens now:

  • Every push to main → auto-deploys to storybook.ourlantern.app
  • Every push to dev → auto-deploys to storybook.dev.ourlantern.app
  • Every feature branch → gets a preview URL

Stakeholders can now:

  • View all components at any time
  • Interact with component variations
  • Share direct links to specific components
  • See the latest designs without running code locally

Questions? Check the full documentation in docs/engineering/deployment/STORYBOOK_DEPLOYMENT.md or ask your engineering team.

✅ Setup complete! Storybook is now live for stakeholders.

Built with VitePress

Copyright © 2026 Lantern