Setup from zero

This guide takes a completely blank computer (no Node.js, no pnpm, maybe no terminal experience) to a running dev server for this kit.

Two paths. Pick one. They both end the same way: you see the site at http://127.0.0.1:3000.

• Path A — Let your AI do it for you. Fastest. Needs an AI tool that can run commands.
• Path B — Do it yourself, step by step. Slower but you understand what happened.

Path A — Let your AI do it

You need an AI coding tool that can read files and run shell commands. Any of these work:

• Claude Code (VS Code extension or CLI)
• Codex (VS Code extension or CLI)
• Gemini Code Assist (VS Code extension) or Gemini CLI
• Cursor, Windsurf, Antigravity (full AI IDEs)

Web chat (ChatGPT.com, Claude.ai, Gemini web) cannot run commands on your machine. Use Path B if that is all you have.

Steps

1. Open this project folder in your AI tool.

2. In the chat panel, type:

   Read agent-skills/get-it-running.md and follow it. Walk me through one step at a time. My computer might not have Node.js or pnpm yet. Ask me before running anything that needs my password.

3. Follow along. The AI will:

   • Detect your operating system.
   • Check what you already have installed.
   • Install Node.js, pnpm, and dependencies.
   • Start the dev server.
   • Tell you to open http://127.0.0.1:3000.

4. If the AI gets stuck or something looks wrong, switch to Path B below and do it yourself.

Path B — Do it yourself

Pick your operating system.

macOS

1. Open Terminal

Press Cmd+Space, type "Terminal", press Enter.

2. Check if you already have Node.js

In Terminal, type:

node -v

• If you see something like v20.12.0 or higher: skip to step 4.
• If you see command not found: go to step 3.

3. Install Node.js

The simplest way, no account needed:

1. Go to nodejs.org.
2. Click the "LTS" download button (big green one).
3. Open the downloaded .pkg file.
4. Follow the installer. Default choices are fine.
5. Close and reopen Terminal.
6. Run node -v again. You should see a version number now.

(Alternative: if you already have Homebrew, run brew install node.)

4. Enable pnpm

Node comes with a tool called Corepack that gives you pnpm. In Terminal:

corepack enable
corepack prepare pnpm@10.28.2 --activate

Verify:

pnpm -v

You should see a version number like 10.28.2.

5. Install this kit's dependencies

Navigate to the project folder. Use Finder to drag the folder into Terminal and it will paste the path, or type cd and drop the folder onto Terminal.

Then:

pnpm install

This downloads everything the kit needs.

6. Start the dev server

pnpm dev

You should see a line that ends with http://127.0.0.1:3000/. Open that URL in your browser. The kit is running.

To stop the server later, come back to Terminal and press Ctrl+C.

Windows

1. Open PowerShell

Press the Windows key, type "PowerShell", click "Windows PowerShell".

2. Check if you already have Node.js

In PowerShell, type:

node -v

• If you see v20.12.0 or higher: skip to step 4.
• If you see a "not recognized" error: go to step 3.

3. Install Node.js

The simplest way, no account needed:

1. Go to nodejs.org.
2. Click the "LTS" download button.
3. Open the downloaded .msi file.
4. Follow the installer. Default choices are fine.
5. Close and reopen PowerShell.
6. Run node -v again.

(Alternative: if you use winget, run winget install OpenJS.NodeJS.LTS.)

4. Enable pnpm

corepack enable
corepack prepare pnpm@10.28.2 --activate

Verify:

pnpm -v

If corepack gives a permission error, open PowerShell "as Administrator" (right-click → "Run as administrator") and retry.

5. Install this kit's dependencies

Navigate to the project folder. In File Explorer, open the kit folder, click in the address bar, type powershell and press Enter. That opens PowerShell inside the folder.

Then:

pnpm install

6. Start the dev server

pnpm dev

Open http://127.0.0.1:3000/ in your browser. The kit is running.

To stop the server later, come back to PowerShell and press Ctrl+C.

Common errors and fixes

"command not found: node" (Mac) or "'node' is not recognized" (Windows)

Node is not installed, or your terminal was open before install finished. Close and reopen the terminal, try again.

"command not found: pnpm"

Run corepack enable first. If that fails, install pnpm directly with:

npm install -g pnpm@10.28.2

"EACCES" or permission denied

On macOS, avoid sudo. Instead, use a Node installer that installs to your home directory (the official installer is fine), or use a version manager like nvm.

On Windows, reopen PowerShell as Administrator for the failing command.

Port 3000 already in use

Something else is using the port. Either stop the other process, or change the port in vite.config.ts:

server: { port: 3001, host: '127.0.0.1' },

Dev server runs but the page is blank

Open the browser's DevTools (F12) and check the Console tab. Paste any red error text to your AI and ask it to explain.

Verification checklist

You are set up when all of these are true:

• node -v returns v20 or higher.
• pnpm -v returns 10.x.
• pnpm install finished without errors.
• pnpm dev shows http://127.0.0.1:3000/.
• Opening that URL shows the landing page with a hero that says "Your headline goes here."

Once all five are checked, move on to how-to-start.md to start editing with AI.