Stackathon Starter

A vibe-coding hackathon starter. Use the template, prompt Claude Code, push to deploy.

👋 New here? Start with GETTING-STARTED.md. It's a click-by-click walkthrough — no prior Next.js or deploy knowledge needed.

🛠️ Running the hackathon? See MAINTAINER-SETUP.md for organizer notes.

• ⚡ Next.js 16 (App Router) + React 19 + TypeScript
• 🎨 Tailwind v4 + shadcn/ui preinstalled
• 🤖 Claude Code prewired: CLAUDE.md + ready-to-use skills in .claude/skills/
• 🚀 Zero-config deploy — import to Vercel once, then every push to main ships a live URL

Quick start

This repo requires Node 22. If you do not have Node installed, run:

./scripts/setup.sh

If you already have Node but want to ensure the right version is installed, you can also run:

npm run setup

Then install dependencies and start the app:

npm install
npm run dev

Open http://localhost:3000 and start editing src/app/page.tsx.

Building with Claude Code

Open this folder in Claude Code and just describe what you want — it reads CLAUDE.md for the stack and conventions, and has these skills available:

Skill	What it does
ship-it	Build-check, commit, push to main (Vercel auto-deploys)
new-feature	Scaffold a route + components following repo conventions
add-component	Install a shadcn component and wire it in
fix-build	Diagnose and fix a failing build / type error
security-review	Review the staged diff for vulnerabilities before committing
mock-database	Stand up a zero-setup JSON-file store now; upgrade to a real DB later
start-here	Guided first-run walkthrough for beginners
grill-with-docs	Stress-test a plan against your domain model and docs

Add more shadcn components anytime: npx shadcn@latest add dialog tabs table.

Pre-commit security gate

A Claude Code hook (.claude/settings.json) blocks git commit until the staged changes pass a security review. When Claude tries to commit, the hook runs .claude/hooks/security-precommit.sh; if the staged content hasn't been reviewed, the commit is blocked and Claude runs the security-review skill. A clean review records approval in .claude/.security-review-ok (gitignored) and the commit proceeds. The first time, Claude Code asks you to approve the project hook.

Deploy to Vercel

Deployment is zero-config — Vercel builds Next.js natively, so there's no Procfile, Dockerfile, or any keys to store.

One-time: you can do this entirely from the terminal with npx vercel, or use the web dashboard at vercel.com. If you choose the dashboard, sign in with GitHub or Google, then Add New → Project → Import your repo → Deploy. Vercel auto-detects Next.js; leave the defaults.

After that: every push to main redeploys automatically, and every pull request gets its own preview URL. App-specific env vars (if any) go in Vercel → Project Settings → Environment Variables. Full beginner walkthrough in GETTING-STARTED.md.

A CLI path also works if you'd rather deploy from Claude Code or the terminal:

npm install -g vercel
vercel login
vercel
vercel --prod

If you prefer not to install the Vercel CLI globally, use the project scripts instead:

npm run vercel:login
npm run vercel:link
npm run vercel:deploy

The first vercel command links the project to your Vercel account and creates the deploy settings automatically.

Project layout

src/
  app/            # routes (page.tsx per folder), layout, API routes under app/api/
  components/     # your components
  components/ui/  # shadcn primitives (editable)
  lib/utils.ts    # cn() helper
.claude/skills/   # prewired Claude Code skills

Notes

This template uses Next.js 16 / React 19 / Tailwind v4 — newer than many code assistants expect. CLAUDE.md and AGENTS.md carry the relevant reminders.