Firestarter

Firestarter is a pre-built design system, CMS, and frontend for low to mid-tier client projects. It bridges the gap between bespoke builds and Squarespace/Framer sites for clients who deserve a real CMS and higher design quality.

The system ships a complete set of flexible components and page layouts designed and built to Firebelly’s internal standards. Duplicate the repo, customize design tokens (colors, type, spacing), add any unique components or page templates, and deploy.

Tech Stack

Figma Design System → Storybook → Craft CMS (headless) → Next.js Frontend

Layer	Tool	Purpose
Design	Figma	Design system source of truth
Components	Storybook	Component library with Figma tokens
CMS	Craft CMS 5	Headless content management
Frontend	Next.js 16	App Router, Server/Client Components

Directory Structure

/firestarter
├── /site                 # Next.js + Storybook
│   ├── .storybook/       # Storybook configuration
│   ├── src/
│   │   ├── app/          # Next.js App Router
│   │   ├── components/   # Components with co-located stories
│   │   ├── stories/      # Storybook default stories
│   │   ├── tokens/       # Design tokens from Figma
│   │   └── lib/          # Utilities and API helpers
│
├── /cms                  # Craft CMS (headless)
│   ├── config/           # Craft configuration
│   ├── templates/        # Twig templates (minimal)
│   └── web/              # Public directory
│
└── /docs                 # Project documentation

Documentation

• Backlog — Planned work and ideas
• Changelog — What's been built and when

Design specs and implementation plans live in docs/design-specs/ and docs/implementation-plans/. Each changelog entry links to the relevant spec and plan for deeper context.

Getting Started

Prerequisites

• Node.js (see .nvmrc for version)
• DDEV (for local Craft development)

Install Dependencies

This repo uses a pnpm workspace — the root pnpm-workspace.yaml defines site as a workspace package. A single install from the root handles everything:

# Set correct Node version
nvm use

# Activate the pinned pnpm version
corepack enable

# Installs all dependencies (root + site workspace)
pnpm install

This installs Lefthook and Prettier at the root, site dependencies in /site, and automatically configures pre-commit hooks for formatting, type checking, and linting.

CMS (Craft)

See cms/README.md for Craft setup instructions (DDEV, env file, install, license key).

Frontend (Next.js + Storybook)

The root provides proxy commands for the frontend workspace:

# Start Next.js at localhost:3000
pnpm dev

# Start Storybook at localhost:6006
pnpm storybook

# Rebuild design tokens
pnpm tokens

These proxy to the site workspace via pnpm --filter site. See site/README.md for full frontend setup, component structure, design tokens, and testing.

Craft + Next.js Integration

The frontend fetches content from Craft CMS via GraphQL. The integration includes:

• GraphQL data fetching — site/src/lib/graphql/client.ts wraps fetch with caching
• Live preview — Editors see draft changes in Craft's preview iframe
• Cache revalidation — Webhook from Craft invalidates Next.js cache on publish

Webhook Setup (Cache Revalidation)

When an editor publishes content in Craft, a webhook POSTs to Next.js to purge the cached data so the next visitor sees fresh content.

1. Add environment variables to cms/.env:

REVALIDATION_SECRET=your-random-string
REVALIDATION_URL=http://host.docker.internal:3000/api/revalidate  # local dev

2. Configure the webhook in Craft CP → Settings → Webhooks:

Field	Value
Name	Revalidate Next.js
Sender Class	craft\elements\Entry
Event Name	afterSave
URL	$REVALIDATION_URL
Method	POST
Headers	Content-Type: application/json

3. Set the webhook payload (Twig template):

{% set entryUri = event.sender.uri %}
{% set revalidationSecret = getenv('REVALIDATION_SECRET') %}

{{
  {
    secret: revalidationSecret,
    uri: entryUri
  }|json_encode|raw
}}

You can verify the webhook is working in Craft CP → Utilities → Webhooks, which shows request/response history. See docs/learnings/2026-01-27-on-demand-revalidation.md for details on how revalidation works under the hood.

Environment Variables

Copy the example file and fill in values:

cd site
cp .env.example .env.local

Variable	Purpose
CRAFT_URL	Craft CMS URL (e.g., http://cms.ddev.site)
REVALIDATION_SECRET	Shared secret for webhook validation

The CMS also needs REVALIDATION_SECRET in cms/.env (same value).

Local Development Notes

• Use HTTP (not HTTPS) for CRAFT_URL locally — Node rejects self-signed certs
• To test Craft's live preview feature, you need HTTPS (the CP iframe won't load HTTP content). Run pnpm dev --experimental-https and update PRIMARY_SITE_URL=https://localhost:3000 in cms/.env. Revert to HTTP when done — webhooks won't work over HTTPS locally.
• See docs/learnings/2026-01-27-local-vs-production-config.md for details

Pre-commit Hooks

Lefthook runs automated checks before each commit:

1. Prettier — Auto-formats staged files and re-stages them
2. TypeScript — Full project type check (tsc --noEmit)
3. ESLint — Lints staged JS/TS files only

Jobs run in order. Prettier runs on all supported file types; TypeScript and ESLint only run on JS/TS files in /site.

To format the entire repo manually:

# Format all files
pnpm format

# Check without writing
pnpm format:check

To lint the frontend manually:

# Check for errors
pnpm lint

# Auto-fix (includes import sorting)
pnpm lint --fix

To bypass hooks temporarily (use sparingly):

git commit --no-verify -m "message"

Key Principles

• Client safety — CMS structured so clients can manage content without breaking layouts
• Off-the-shelf components — Most projects use existing components, few custom additions
• Clear separation — Frontend and CMS are distinct, self-contained directories
• Clone and go — New projects clone the repo; no complex setup or shared dependencies