Day 3 — Deploy + CMS

Concepts you need first

1. 1

   What's a headless CMS?

   A CMS that's separate from the website build. Webflow's CMS is built in. With Sanity (or Strapi) the content lives in a separate service that your site pulls from. Means the same CMS can power a website, mobile app, and other platforms.

2. 2

   What's a branch?

   A copy of your codebase. You can work on a new feature (like an About page) in a branch without affecting your live site. Each branch gets its own preview URL on Vercel — perfect for sharing with clients before going live.

3. 3

   What's a commit?

   Logging your changes — saying 'these are saved'. Like a checkpoint.

4. 4

   What's a push?

   Sending your committed changes from your computer up to GitHub.

5. 5

   What's a pull request (PR)?

   A request to merge a branch (e.g. 'about-page') back into the main branch. Lets you review changes before they go live.

6. 6

   What's a merge?

   Combining two branches together — usually merging your feature branch into main once you're happy with it.

7. 7

   Why bother with branches?

   For a brand new project with no users — just push to main, it's fine. For live projects, branches let multiple people work in parallel without stepping on each other, and let you preview changes before anything goes live.

8. 8

   What's a CDN?

   Content Delivery Network — a place to store images and assets so they load fast. Sanity has its own CDN. Use it for content the client will edit (blog post images). For homepage images that don't change, just put them in /public.

9. 9

   What's .env.local? Why doesn't Vercel see it?

   A file in your project that holds secrets (API keys, project IDs). It's gitignored so it never gets pushed to GitHub. That's the point — but it means Vercel doesn't see it either. You have to add the same env vars manually in Vercel's dashboard (Settings → Environment Variables) for production builds to work.

10. 10

    Static vs auto-revalidate (why your CMS update isn't showing)

    When Vercel builds your site, it pre-renders your homepage HTML based on what's in Sanity AT BUILD TIME. After that, Sanity updates won't appear unless you (a) redeploy in Vercel, or (b) set up auto-revalidate so Next.js re-fetches every X seconds. For real client sites, ask Claude to set up revalidate to ~60 seconds.

Initial deploy to Vercel

1. 11

   Start your dev server

   In a terminal tab inside your project folder.

   npm run dev

   copy
2. 12

   Start Claude Code in another tab

   claude --dangerously-skip-permissions

   copy
3. 13

   Push everything to main on GitHub

   For brand new projects with no users, push direct to main. Tell Claude:

   Can you push everything to main on GitHub?

   copy
4. 14

   Vercel auto-deploys

   Once GitHub gets the push, Vercel automatically builds and deploys. Wait ~1–2 min and refresh your live URL.

5. 15

   If Vercel build fails — check env vars

   Most common deploy failure. .env.local doesn't sync. Go to Vercel → your project → Settings → Environment Variables and add them manually. See troubleshooting below.

Install Sanity (headless CMS)

1. 16

   Ask Claude how to add Sanity

   Don't memorise the install command — just ask.

   I want to add Sanity CMS to my site. How can I do that?

   copy
2. 17

   Run the install commands Claude gives you

   Make sure your terminal window is wide — line breaks cause issues. Each command pasted in a fresh terminal tab.

3. 18

   Initialize Sanity Studio

   Sanity will prompt through setup: log in with Google → create new project → name it (e.g. 'h-studio-001') → public dataset visibility → add config files (yes).

4. 19

   Configure Sanity MCP server

   When asked: 'Configure Sanity MCP server for Claude Code?' — say YES. This is what makes the rest magical.

5. 20

   Project settings

   TypeScript: yes. Embedded Sanity Studio: yes. Route: /studio. Template: clean project with no predefined types. Add project ID and dataset to .env.local: yes.

6. 21

   Restart Claude Code if MCP didn't connect

   Type /exit, then run claude --dangerously-skip-permissions again.

   /exit

   copy
7. 22

   Verify Sanity MCP is connected

   /mcp

   copy
8. 23

   Open Sanity Studio locally

   You should see Sanity Studio with no document types yet — that's correct.

   http://localhost:3000/studio

   copy

Create your first content type

1. 24

   Tell Claude what to build

   For demos, let Claude make a sensible schema. For real client work, specify exactly what fields you need.

   I want to add a portfolio document type to my CMS. Use it for the Selected Work section on the homepage. Make up a schema that makes sense, add 4 sample items, and configure the homepage to pull dynamically from Sanity.

   copy
2. 25

   Refresh Sanity Studio in browser

   You should now see your new document type with sample items inside.

3. 26

   Test that the homepage updates

   Edit one of the sample items in Sanity Studio (change a title), click Publish, refresh your homepage. The change should appear.

4. 27

   If it doesn't update — it's probably caching

   I updated the title in Sanity Studio but the homepage still shows the old version. Why?

   copy

Branches + pull requests (full manual)

1. 28

   Create a new branch and push to it

   When working on something risky (like adding the CMS), use a branch instead of pushing direct to main.

   Create a new branch called sanity, push everything to that branch, and upload my env vars to Vercel.

   copy
2. 29

   Vercel auto-creates a preview deployment

   Open Vercel — you'll see a new deployment under your branch name with its own preview URL. Share with clients/teammates for review.

3. 30

   Fix any build errors

   If the Vercel build fails, copy the error and paste into Claude.

   [paste the Vercel build error here]

   copy
4. 31

   Open a pull request

   When the branch is approved, ask Claude to open a PR.

   Can you open a pull request for this branch to go into main?

   copy
5. 32

   Have Claude review the PR before merging

   Catches issues before they go live. Claude takes on a 'reviewer' role and often spots things.

   Can you review the PR and then merge it into main?

   copy

Going live with the CMS

1. 33

   Add Sanity env vars to Vercel (FIRST TIME ONLY)

   Go to vercel.com → your project → Settings → Environment Variables. Add NEXT_PUBLIC_SANITY_PROJECT_ID, NEXT_PUBLIC_SANITY_DATASET, SANITY_API_READ_TOKEN, SANITY_API_WRITE_TOKEN. Get the values from your local .env.local file. Tick all 3 environments (Production, Preview, Development). Mark the two API tokens as Sensitive.

2. 34

   Register Sanity Studio with your production domain

   After deploy, visit yoursite.com/studio. It'll prompt you to register — stops other sites using your CMS. Click 'Add studio host'. Use the FULL URL including /studio (e.g. https://yoursite.vercel.app/studio).

3. 35

   Add team members or clients to Sanity

   Sanity dashboard → Members → Add member. Free plan includes 20 seats.

4. 36

   Test live updates

   Edit something in Sanity Studio on your live site. Click publish.

5. 37

   If updates don't appear

   Most likely your homepage is statically pre-rendered (locked to build time). Two options: (1) Manual: Vercel → Deployments → ⋯ → Redeploy. (2) Better: ask Claude to set up auto-revalidate.

   Set up Next.js to revalidate the homepage every 60 seconds so Sanity updates appear automatically without a redeploy.

   copy

Connect a custom domain

1. 38

   Buy a domain through Vercel

   Vercel → Domains → Buy. Good prices. Tip: .xyz domains are $2 for the first year.

2. 39

   Or connect a domain you already own

   Vercel → Project → Settings → Domains → Add. Type your domain (e.g. yoursite.com) — Vercel gives you DNS records to add at Namecheap/GoDaddy/etc.

3. 40

   Set up a staging subdomain

   Add staging.yoursite.com → set it to 'Preview' instead of 'Production'. Now branches deploy to that subdomain.

4. 41

   Vercel + Sanity pricing

   Both free for portfolios and small client sites. Only need paid plans on big sites with serious traffic — at that point the cost is trivial.

Useful tips

1. 42

   Use rems/ems instead of pixels (if you prefer)

   Julian's tip when asked: easiest way is to tell Claude 'convert it to rems'. If it keeps reverting to pixels, add 'do not use pixels, use rems and ems' to your CLAUDE.md file.

2. 43

   Use /resume to recover a previous Claude Code conversation

   Type /resume inside Claude Code — gives you a list of previous conversations. Works ~90% of the time.

   /resume

   copy
3. 44

   Use a CLAUDE.md file for persistent context

   Anything you want Claude to remember every time — your experience level, brand guidelines, coding preferences (rems vs pixels), tone. Add it to a CLAUDE.md file in your project root and Claude reads it before every action.

4. 45

   When stuck on a hard prompt — describe it like to a developer

   Don't just say 'fix it' or 'match Figma'. List exact issues: 'The H1 has no overlay. The image is too big. The button needs to align with the text on the right.' Be specific.

5. 46

   Switch to Codex if Claude is being weird

   Sometimes Claude has off days. Open a new terminal tab and type 'codex' instead of 'claude'. Same workflow, different model.

   codex

   copy
6. 47

   GitHub commits page can be cached

   If you push something and don't see it on GitHub's commit list, hard refresh the page (Cmd + Shift + R) before assuming the push failed. Or run: git ls-remote origin main

   git ls-remote origin main

   copy
7. 48

   Pasted token looks too short? Re-paste it

   When adding env vars to Vercel, the value field shows dots. If a token's dots are way shorter than the field width, the paste didn't take. Click the field, clear it, paste again.

Quick version — Ship Studio

Ship Studio gives you a visual UI for branches, pull requests and merges. Click 'new branch' → name it → make changes → click sync → 'submit for review' to open a PR → click merge. Same Git under the hood, just visual. Free. Also has a Backups feature that lets you restore to any previous GitHub push with one click.

1. 49

   Open the Branches panel

   In Ship Studio, click Branches in the sidebar — see all branches visually.

2. 50

   Click 'New branch'

   Type a name (e.g. 'about-page') → click create. Ship Studio switches you to the new branch automatically.

3. 51

   Make your changes

   Use Claude Code as normal — work on the about page, refine, etc.

4. 52

   Click 'Sync'

   Pushes your branch changes to GitHub. You can grab the Vercel preview URL from inside the app.

5. 53

   Click 'Submit for review'

   Opens a pull request for you. Add a description if needed → click Create pull request.

6. 54

   Click 'Merge'

   Merges the branch into main. You can also tell Claude to review the PR first.

7. 55

   Restoring a backup

   If something breaks, go to Backups in Ship Studio. Every push to GitHub is a restore point. Click restore on any of them.