The Essential Ingredients

# If Homebrew itself isn't installed yet (the apothecary door is locked)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Git — the owl post (version control)
brew install git

# Bun — the wand (package manager + runtime)
brew install oven-sh/bun/bun

# Node.js — the backup wand (some tools still expect it)
brew install node

Why keep Node around? Bun handles nearly everything, but certain Vite plugins, CL environments, and Lovable's own deploy pipeline still assume Node is present. Think of it as carrying a spare wand in your robe pocket — Ollivander wouldn't approve, but Moody would.

That's it. Three commands, three tools. The workstation is equipped. Notice what didn't happen: nobody had to describe what they wanted in natural language and hope for the best. brew install bun doesn't "interpret your intent." It installs Bun. Every time. This is the comfort of deterministic tooling — the spell does what the spell does.

Why Bun?

The install speed is the headline. Bun resolves and writes node_modules in a fraction of the time, with roughly a sixth of the system calls. For a Lovable project with dozens of dependencies, this is the difference between waiting for the Hogwarts Express and Apparating directly to the platform.

Does It Actually Work with Lovable Projects?

Yes. Lovable generates standard Vite + React + TypeScript projects. Bun reads the same package.json, resolves from the same npm registry, and produces a structurally identical node_modules directory. The commands map directly:

bun run dev starts the Vite dev server with full hot module replacement (HMR). Edit a .tsx file and the browser updates in milliseconds — like a Remembrall that glows the instant something changes. There is no "I think you meant to update the other component." You changed line 42, the browser reflects line 42.

This feedback loop is instantaneous and literal, which is what makes local development so much more precise than prompting an AI agent to make the same change for you.

The Lockfile Question (Important)

This is where discipline matters — Hermione-level discipline.

Bun creates its own lockfile (bun.lock in Bun v1.2+, or the binary bun.lockb in older versions). It does not update npm's package-lock.json. This means after running bun install, you have two lockfiles in the project — two sources of truth, which is one too many.

The rule: keep package-lock.json as the canonical lockfile. Lovable, Cloudflare Pages, and any CI pipeline all expect it. Bun's lockfile stays local-only.

# Add to .gitignore — keep bun's lockfile out of the repo
echo "bun.lock" >> .gitignore
echo "bun.lockb" >> .gitignore

If you add a new dependency:

bun add some-package        # fast install, updates package.json
npm install                 # regenerate package-lock.json for the repo
git add package.json package-lock.json
git commit -m "add some-package"

Slightly tedious? Yes. But Hermione didn't get twelve O.W.L.s by cutting corners. The alternative, committing bun.lock alongside package-lock.json — confuses deploy platforms that auto-detect package managers and creates merge conflicts that are genuinely unpleasant to resolve.

The Golden Rules

1. Never work directly on main!

git checkout -b feature/my-changes

If you edit main locally while someone is editing simultaneously in Lovable's UI, both sides push to the same branch and you get merge conflicts! Lovable-generated code is verbose and machine-structured. Resolving conflicts verbose code is like trying to decode a passage of Ancient Runes where every line looks almost identical.

Work on a branch. Merge to main when you're ready. This keeps your in-progress work invisible to Lovable until you choose to surface it. Use Git-Flow for precision when you want to be professional and work with others... we'll cover this another day.

2. Always pull before you push.

git checkout main
git pull origin main --rebase
git merge feature/my-changes
git push origin main

Lovable may have pushed new commits to main while you were working. Doing this pull before merging ensures your changes layer up cleanly on top. It's like arriving at the Great Hall after everyone's already seated, rather than crashing into the middle of the tables.

3. One editor at a time on the main branch.

If someone is actively prompting in Lovable, don't push to main from your terminal simultaneously. Take turns. Coordinate. Send an owl!

What Happens When You Push to Main

The moment your commits land on main, two things happen in parallel:

• Lovable picks up the changes within seconds and syncs them into its editor
• Cloudflare Pages (if connected) triggers a new build and deploy

This is the complete flow: your local edit → Git → GitHub → Lovable + Cloudflare. Every link in the chain is automatic. You just have to push and pull to get your Lovable changes. Lovable → GitHub (→ Cloudflare) → Git → local edits. Cycle and repeat.

Building for Production Locally

# Build (produces dist/ directory)
bun run build

# Preview the production build before deploying
bun run preview
# Serves dist/ on a local port — verify everything works

Optional Deploying Directly (Apparition, from the hosting guide)

# Build and deploy to Cloudflare Pages in one shot
bun run build && npx wrangler pages deploy dist --project-name=safe-trace-website

Merging Your Work Back

git add .
git commit -m "feat: description of changes"
git checkout main
git pull origin main --rebase
git merge local-dev
git push origin main
# Lovable syncs within seconds. Cloudflare rebuilds automatically.