Module 3: Local-First Development

Cloud IDEs hide errors behind deploy logs and strip you of control when you need it most. This module gets everything running on your machine (server, auth, payments) so the feedback loop is instant and the environment matches production.

Key idea

If it does not run on your machine, you do not control it. Local-first means you own the feedback loop.

Your first build day

Time: about 3 hours for a clean run, longer if your stack has extra services
You finish with: a working Next.js app running on localhost with routing, one real feature, and a clean build you can deploy
Start by copying the bootstrap script below into Claude and following the instructions it gives you

Plan, build, and prove. All running on your machine.

Bootstrap script

Copy this entire block into Claude. It will create a Next.js app, add routing, build one working feature, and hand you back a proof packet when it is done. Read through it first so you know what it will do.

CLAUDE AGENT: Bootstrap a Next.js App

You are Claude. You are setting up a new project from scratch.

GOAL
Create a working Next.js app with TypeScript, one page route,
one working feature (a simple form or data display), and a
clean build.

REPO GUARDRAILS
  pwd: (user will fill in their project path)
  Branch: main
  Working tree must be clean before you start

ALLOWED FILES (only touch these)
  package.json
  tsconfig.json
  next.config.ts
  app/layout.tsx
  app/page.tsx
  app/globals.css
  app/[one-feature]/page.tsx
  (you may create new files inside app/ only)

DO NOT TOUCH
  node_modules/
  .git/
  Any file outside the app/ directory unless listed above

RULES
  One issue at a time. Do not combine unrelated changes.
  Minimal diff. Do not rewrite files that do not need it.
  If something is unclear, stop and ask.

STEPS
  1. Initialize the project: npx create-next-app@latest
     Use TypeScript, App Router, Tailwind, ESLint
  2. Clean up the default page to something minimal
  3. Add one new route with a simple working feature
  4. Run these verification commands and report results:
       npx tsc --noEmit
       npm run build
  5. If either fails, fix the issue and re-verify

OUTPUT
Return a HANDOFF PACKET with:
  pwd
  git remote -v
  git branch --show-current
  git status --short
  Summary of what you built
  Files changed
  Verification results
  git show --stat HEAD
  git show --name-only HEAD

After Claude finishes, run the verification commands yourself to confirm. If the build passes, commit and move on.

Your first loop

Once the bootstrap is done, every change you make follows the same cycle. It is simple, but sticking to it is what keeps things from going sideways.

1.Write a short spec describing the change you want. Include file targets and what done looks like.
2.Paste the spec into Claude. It changes the code and gives you a diff.
3.Run typecheck and build on your machine. If something fails, paste the error back to Claude with the same file list.
4.When the build is clean, commit. Paste the handoff packet into your notes or your next session so context carries forward.

That is one full cycle. Repeat it for every feature, every fix, every refactor. The loop does not change.

What good looks like

You know it is working when your build passes locally and the diff matches your spec.

One clean commit with only the files you planned to change.

Outcome

You own the full stack. No platform decides when you can ship.

Deliverable

A feature branch built, tested, and shipped entirely from localhost.

Lessons

·What you give up with cloud IDEs and what you gain by going local
·The VS Code extensions that actually matter for AI-assisted work
·Getting server, database, and auth running on localhost together
·Hot reload: why sub-second feedback changes how you build
·Writing atomic commits that tell a clear story
·Environment parity from local to preview to production
·Keeping .env files sane across three environments
·A git branch strategy that works when you’re the only developer
·Port conflicts, service collisions, and how to avoid them
·Debugging on your machine vs. debugging through deploy logs
·Terminal muscle: split panes, task runners, working faster
·Where localhost lies to you about production behaviour

Exercises

·Get auth and payments running on localhost. Hit every route before you push.
·Ship a feature from local dev to preview to production. Note every config difference.
·Write a .env.example that documents every variable. Commit it as a guardrail.

Proof Checklist

Proof

☐Feature behaves the same on localhost and the preview deploy
☐Every environment variable documented in .env.example
☐npm run build exits clean
☐git show --stat HEAD shows only the files you meant to touch
☐git show --name-only HEAD lines up with your declared targets

All modules Next: Verification and Proof