Get Started

Fork Buttercut, edit site.config.ts and content/demo/, deploy. Each step includes a copy-paste AI prompt.

Overview

Most forks only touch two places — config for structure, content for copy.

Edit site.config.ts for navigation, blocks, and integrations. Edit content/demo/ for hero copy and page JSON. Deeper layout changes stay in src/custom/ so theme updates stay mergeable.

Steps

Follow in order — or paste the AI prompt under each step into your agent.

  1. 1.

    Clone or deploy

    Fork the repo or use the Vercel deploy button in the README. Run npm install && npm run dev — the site works with no .env file.

    Repo root · README

    AI prompt

    I forked Buttercut (github.com/kaiiiichen/buttercut). Help me run npm install && npm run dev, confirm localhost:3000 loads, and summarize which folders I'll edit first.
  2. 2.

    Configure site.config.ts

    Set title, URL, nav, home blocks, brand, and integrations. Override only what differs from src/lib/config/defaults.ts.

    site.config.ts

    AI prompt

    Update site.config.ts for my site: [title, description, siteUrl, nav links, home.blocks order]. Match Buttercut types in src/lib/config/types.ts. Show the diff before applying.
  3. 3.

    Replace content

    Hero copy: content/demo/intro.md. Page JSON (about, projects, misc) under content/demo/ — wire into routes you add under src/app/. No React needed for text changes.

    content/demo/

    AI prompt

    Rewrite Buttercut content for [describe your site]. Edit content/demo/intro.md and the JSON files under content/demo/. Keep existing schemas — do not invent new fields.
  4. 4.

    Enable integrations (optional)

    Toggle integrations.* in site.config.ts. Add env vars from .env.example. Preview live widgets on /sandbox.

    site.config.ts · .env · /sandbox

    AI prompt

    Enable [GitHub / weather / Last.fm] in my Buttercut fork. Update site.config.ts integrations, list required .env vars from .env.example, and tell me what I should see on /sandbox.
  5. 5.

    Customize blocks (optional)

    Swap or add home sections via src/custom/register.ts. See src/custom/blocks/MyHero.tsx for the override pattern.

    src/custom/

    AI prompt

    Add a custom Buttercut home block for [describe section]. Follow MyHero.tsx, register in src/custom/register.ts, and add { id, enabled: true } to home.blocks.
  6. 6.

    Deploy

    Push to GitHub and connect Vercel. Set optional env vars in the dashboard. Missing credentials never break the build.

    Vercel · .env.example

    AI prompt

    Prepare my Buttercut fork for Vercel: run npm run build, list env vars to set, and confirm site.config.ts siteUrl matches my production domain.

site.config.ts

Key fields you will edit on a fork.

  • site.title / description / siteUrl

    Metadata, nav brand, Open Graph

  • nav[]

    Header links — internal paths or external URLs

  • home.heroLayout

    "product" for docs sites; "personal" for avatar + greeting

  • home.blocks[]

    Home section order and visibility

  • brand.avatar / theme / attribution

    Hero portrait, CSS tokens, footer credit

  • integrations.*

    GitHub, weather, Last.fm toggles and coordinates

Project layout

Where files live in the repo.

buttercut/
├── site.config.ts          # Your overrides
├── content/demo/           # Hero + page copy (Markdown + JSON)
├── src/app/                # Routes — add pages here
├── src/blocks/             # Built-in home sections
├── src/components/         # UI primitives
└── src/custom/register.ts  # Block overrides

Master AI prompt

Paste into Cursor, Claude Code, or similar — fill in the bracketed sections.

AI prompt

You are customizing Buttercut — a Next.js 16 theme (App Router, TypeScript, Tailwind 4).

Rules:
- Prefer site.config.ts and content/demo/ before editing React.
- New home sections: src/custom/blocks/ + src/custom/register.ts.
- Reuse src/components/ primitives (see buttercut.kaichen.dev/components).
- Integrations fail open — missing env vars must not break the build.

My site:
- Audience: [who visits]
- Pages: [home, about, product, …]
- Tone: [professional, playful, …]
- Brand: [colors, avatar, social links]
- Integrations: [GitHub, weather, none]

Start with a plan for site.config.ts and content/demo/intro.md, then implement step by step.

Working with AI

Tips that keep agents aligned with Buttercut conventions.

  • Give the agent site.config.ts, content/demo/, and this Get Started page as context.
  • Ask for content changes first, then config, then new routes or custom blocks.
  • Point it at /design and /components on buttercut.kaichen.dev so it reuses existing UI.
  • Keep theme-core edits in src/custom/ — easier to merge upstream updates.