novi-lessons/Les14-Cursor-Vercel-Deploy/Les14-Lesstof.md

# Les 14 — Lesstof
## Cursor + Vercel: van leeg project naar preview-deploys

**Vak:** AI-Assisted Development
**Opleiding:** NOVI Hogeschool Utrecht
**Vorige les:** Les 13 — Agents
**Volgende les:** Les 15 — RAG + Embeddings

---

## Doel van deze les

Aan het einde van deze les heb je:

- Een vers Next.js project gescaffold via `npx create-next-app`
- Een GitHub-repo met je code
- Een Vercel-project met productie-URL én preview-URL's per branch
- Vercel CLI lokaal gekoppeld + één keer `vercel env pull` gedaan
- Een werkende `.cursor/rules/general.mdc` en `AGENTS.md` in je repo
- Twee features gebouwd via Cursor in eigen branches → twee preview-URL's
- Eén Pull Request gemerged naar productie

---

## 1. Scaffolden met `npx create-next-app`

### Wat het doet

`create-next-app` is het officiële scaffold-commando van het Next.js team. Eén commando, een paar interactieve vragen, en je hebt een werkende Next.js-app met sane defaults.

```bash
npx create-next-app@latest mijn-portfolio
```

### De prompts uitgelegd

| Vraag | Aanbevolen | Waarom |
|-------|-----------|--------|
| TypeScript? | **Ja** | strict typing voorkomt veel bugs |
| ESLint? | **Ja** | code-style consistency |
| Tailwind CSS? | **Ja** | utility-first styling, breed gebruikt |
| `src/` directory? | **Ja** | houdt project-root schoon |
| App Router? | **Ja** | de moderne Next.js flow (server components) |
| Turbopack? | **Ja** | snellere dev-builds |
| Import alias? | **`@/*`** | `@/components/foo` ipv `../../components/foo` |

### Wat je krijgt

```
mijn-portfolio/
├── .gitignore          # node_modules, .next, .env.local zijn al gegitignored
├── next.config.ts
├── package.json
├── tsconfig.json
├── src/
│   └── app/
│       ├── layout.tsx  # root layout
│       ├── page.tsx    # homepage
│       └── globals.css
└── public/
```

Direct `npm run dev` → `localhost:3000` werkt. Vanaf hier ben je productief.

---

## 2. Git + GitHub

### Init en eerste push

```bash
git init
git add .
git commit -m "init"
git branch -M main

# Met gh CLI (snelst):
gh repo create mijn-portfolio --public --source=. --push

# Of handmatig:
# 1. github.com → New repository → naam → Create (leeg, GEEN README)
# 2. git remote add origin <url>
# 3. git push -u origin main
```

### Veelgemaakte fouten

| Fout | Oplossing |
|------|-----------|
| `gh: command not found` | `brew install gh` (Mac) / `winget install GitHub.cli` (Windows) |
| `Authentication required` | `gh auth login` doorlopen |
| `error: src refspec main does not match any` | Eerst `git add . && git commit -m "init"` |
| `fatal: remote origin already exists` | `git remote remove origin` en opnieuw |

### Wat zit er NIET in je commit

Check je `.gitignore` — Next.js zet er standaard de juiste regels in:

```
node_modules/
.next/
.env.local
.env*.local
```

**Belangrijk:** controleer altijd na je eerste push op github.com dat `.env.local` daar NIET staat. Een gelekte secret-key is dezelfde dag onveilig.

---

## 3. Vercel — drie stappen naar productie

### Project importeren

1. Ga naar **vercel.com/new**
2. Klik **Import Git Repository**
3. Kies je `mijn-portfolio` repo
4. Framework auto-detect: **Next.js**
5. Klik **Deploy**

Wacht ±45 seconden. Wat Vercel doet:
- Kloont je repo
- Detecteert framework
- Draait `npm install`
- Draait `npm run build`
- Deploy't naar Edge Network
- Geeft je een productie-URL

### Twee URL-types

| Type | URL-format | Trigger |
|------|------------|---------|
| **Productie** | `mijn-portfolio-<scope>.vercel.app` | push naar `main` |
| **Preview** | `mijn-portfolio-git-<branch>-<scope>.vercel.app` | push naar elke andere branch |

### Wat je vanaf nu krijgt zonder extra werk

- Elke push naar GitHub → automatische deploy
- Elke nieuwe branch → eigen preview-URL
- Pull Request → Vercel-bot post preview-URL als comment
- Productie-URL update vanzelf bij merge naar `main`

---

## 4. Environment Variables in Vercel

### Drie environments

| Environment | Actief bij |
|-------------|-----------|
| Production | deploys vanaf `main` |
| Preview | alle andere branches |
| Development | `vercel dev` lokaal |

Je kunt env vars in één, twee of alle drie tegelijk zetten.

### `NEXT_PUBLIC_` prefix

| Prefix | Wat gebeurt | Voorbeeld |
|--------|-------------|-----------|
| `NEXT_PUBLIC_FOO` | wordt in browser-bundle gestopt | publieke API-URL, Supabase anon-key |
| `FOO` (geen prefix) | alleen server-side beschikbaar | OpenAI key, Stripe secret, DB password |

**Regel:** zet `NEXT_PUBLIC_` ALLEEN op variabelen die echt publiek mogen zijn. Twijfel? Geen prefix.

### Via het dashboard

Settings → Environment Variables → Add. Vul naam + waarde, kies environments, save.

---

## 5. Vercel CLI

### Installeren

```bash
npm i -g vercel
vercel login          # opent browser voor auth
```

### Belangrijkste commando's

```bash
vercel link                          # lokale folder → Vercel project
vercel env pull .env.local           # productie env vars → lokaal
vercel env pull --environment=preview .env.local

vercel env add OPENAI_API_KEY production
vercel env rm OPENAI_API_KEY production
vercel env ls                        # lijst alle vars

vercel                               # interactieve deploy
vercel --prod                        # productie deploy (handmatig)

vercel logs                          # runtime logs
vercel logs --follow                 # stream logs live
```

### Typische workflow

```bash
# Project klaarzetten (eenmalig):
vercel link

# Bij elke nieuwe env var op productie:
vercel env pull .env.local

# Bij env var rotatie:
vercel env rm DATABASE_URL production
vercel env add DATABASE_URL production
```

---

## 6. Cursor — de IDE

### Wat is Cursor

Cursor is een VS Code-fork met AI als kernfeature. Niet een extensie — het is de editor. Werkt met Claude, GPT, Gemini en lokale modellen.

### Cursor 3 — twee windows

In Cursor 3 zijn er **twee hoofdvensters**:

| Window | Wat je er doet | Switch met |
|--------|----------------|-----------|
| **Editor Window** (classic) | Code schrijven en reviewen — als VS Code | Cmd+Shift+N → Editor |
| **Agents Window** | Meerdere agents parallel managen | Cmd+Shift+N → Agents |

**Sneltoets om te onthouden:** `Cmd+Shift+N` switcht tussen beide.

**Binnen het Editor Window:**
- **Cmd+L** — chat-paneel (kies modus: Ask / Agent / Plan)
- **Cmd+K** — inline edit op selectie
- **Tab** — accepteer AI auto-completion
- **Cmd+P** — file search (zoals VS Code)

**Binnen het Agents Window:**
- Overzicht met lokale, cloud en remote agents
- Op één plek alle running + done agents

**Gouden regel:**
- Code schrijven of 1 feature bouwen → **Editor Window** + **Agent mode** in chat
- Meerdere features parallel → **Agents Window** met Background agents
- Snelle tweak in 1 file → **Cmd+K**

> **Versie-noot:** info hieronder is gebaseerd op de officiële Cursor 3 documentatie (`cursor.com/docs`). Cursor 3.7 en hoger heeft alle besproken features. Sommige UI-details kunnen per minor-versie iets verschillen.

### Editor Window — stap voor stap

Je hoofdwerkplek voor code:

1. **Cmd+Shift+N** — switcht naar Editor Window (als je in Agents Window zat)
2. Layout: file explorer links, editor midden, terminal beneden (klassieke VS Code-stijl)
3. **Cmd+L** opent chat-paneel rechts
4. Voor snelle inline edits: selecteer code → **Cmd+K** → beschrijf wijziging
5. Cursor toont **diff inline** in de editor (niet in een aparte panel)
6. **Tab** om te accepteren, **Esc** om te rejecten
7. **Cmd+P** voor file search
8. **Tab** accepteert AI auto-completion suggesties

**Wanneer:** je standaard coding-flow, files reviewen met split screens, VS Code extensies gebruiken (linters, formatters, debugger).

**Tip:** kun je Cursor laten starten in Editor Window als default? Ja. Settings → "Open Agents Window on startup" → uit. Of start vanuit terminal met `cursor --classic`.

### Agent mode (binnen chat in Editor Window) — stap voor stap

De AI-modus *binnen* het chat-paneel:

1. **Cmd+L** opent chat-paneel rechts (in Editor Window)
2. Bovenaan chat: **mode-selector** → kies **"Agent"**
3. Typ de **hele taak** (niet een specifieke kleine wijziging)
4. *"Bouw een /about pagina met team-grid in onze huisstijl"*
5. **Enter** — agent start zelfstandig
6. Cursor toont een lopende **takenlijst** + voortgang per stap
7. Agent edit meerdere files, runt terminal-commando's (vraagt vooraf), kan zelfs **web browsen**
8. **Geen limiet** op aantal tool-calls per taak
9. Aan het einde: samenvatting → **Keep / Accept all** of per file

**Wanneer:** grotere features die meerdere bestanden raken, refactors, nieuwe pagina's of API-routes.

**Belangrijke tip:** hou je prompt specifiek. *"Bouw een about-pagina met team-grid"* = goed. *"Bouw een mooie website"* = veel te open.

### Background agents (Agents Window) — stap voor stap

**Async cloud-based agents** in geïsoleerde VMs:

**Cmd+Shift+N** → Agents Window opent.

**Een agent aanmaken:**
1. In Agents Window: klik **New agent** (of `+`)
2. Kies environment: **local / cloud / remote SSH**
3. Beschrijf de taak — specifiek, als een ticket
4. Optioneel: branch-naam (`feature/about`)
5. Klik **Start**
6. **Cmd+Shift+N** terug naar Editor Window — agent babysit zichzelf

**Resultaat ophalen:**
1. **Cmd+Shift+N** naar Agents Window
2. Klare agents staan op **Done** in de agents-lijst
3. Klik agent → zie **diff + commit message + alle stappen**
4. **Open in PR** → automatische PR op GitHub
5. Vercel maakt preview-URL → review → merge

**Triggers van buitenaf:** Background agents kun je in Cursor 3 ook starten vanuit je telefoon, Slack, GitHub of Linear — handig tijdens vergaderingen.

**Wanneer:** 2–4 parallelle features, lange refactors die je niet wilt babysitten, taken vanaf mobiel.

### Context — `@`-mentions

In chat type je `@` voor een autocomplete. Wat je kunt mention'en:

| Tag | Wat het doet |
|-----|--------------|
| `@file:foo.tsx` | inclusief één specifiek bestand |
| `@folder:components` | hele map als context |
| `@code:functionName` | losse functie of class |
| `@docs` | externe documentatie |
| `@web` | live web-search |
| `@git` | git history / blame |
| `@recommended` | Cursor suggereert zelf relevante bestanden |

**Tip:** hou de scope klein. Veel mentions in één chat verslechtert de output, niet verbetert.

### Cursor Rules

Markdown-bestanden in `.cursor/rules/` die aan elke prompt worden toegevoegd als systeem-instructie.

**Voorbeeld `.cursor/rules/general.mdc`:**

```markdown
---
description: Algemene project-conventies
alwaysApply: true
---

- TypeScript strict mode
- Tailwind voor styling — geen CSS modules
- Server components by default; "use client" alleen waar nodig
- Imports met @/ alias
- Geen any-types
```

YAML front-matter opties:
- `alwaysApply: true/false` — actief in elke prompt
- `globs: ["**/*.test.ts"]` — alleen actief op matching bestanden
- `description: "..."` — wat de rule doet

### Project context — `AGENTS.md`

Eén markdown-bestand in je repo-root dat beschrijft:
- Tech stack + waarom die keuzes
- Architectuur en belangrijke patronen
- Hoe lokaal draaien, hoe deployen
- Pointers naar belangrijke bestanden

`AGENTS.md` wordt door Cursor, Claude Code én GitHub Copilot gelezen. Eén file, meerdere tools.

### Background agents — async cloud

Tweede Cursor-sessie die asynchroon op een feature werkt, in een eigen Git branch, in een aparte tab.

**Workflow:**
1. Beschrijf feature → klik "open in background"
2. Agent werkt in eigen branch, jij blijft in main editor
3. Agent meldt zich klaar → review diff → apply/iterate/discard

**Wanneer:** voor parallelle features. Drie of vier agents tegelijk is normaal.

### Top 7 tips voor power-users

1. **Cmd+I** voor Composer met multi-file context (niet alleen Cmd+L)
2. **`@-recommended`** laat Cursor zelf relevante bestanden voorstellen
3. **Plan + Apply per stap** — niet alles in één klap accepteren
4. **`alwaysApply: false`** rules voor opt-in conventies
5. **Auto-mode** — Cursor kiest beste model per taak
6. **Cmd+Shift+Enter** voor diff-preview vóór accept
7. **Notepads** — herbruikbare prompt-snippets per project

---

## 7. De feature-workflow

### Vijf stappen, één feature

```
1. Plan      → Cursor chat: beschrijf de feature, vraag plan
2. Branch    → git checkout -b feature/x (Cursor kan dit ook)
3. Build     → Apply het plan, eventueel inline tweaks
4. Commit+   → git add . && git commit -m "feat: x" && git push
   Push
5. Preview   → Vercel maakt preview-URL, test & itereer
```

### Eén feature ≈ 10 minuten

Inclusief AI denkwerk. Wat dit versnelt is niet dat AI mooier code schrijft — het is dat de **cycle korter wordt**.

### Anti-patterns

- Geen branch maken, direct op `main` werken (geen preview, geen rollback)
- 5 features in één commit ("WIP" commits)
- Plan niet lezen → Apply → het deugt niet → terugkrabbelen
- Background agents starten zonder duidelijke prompt → bagger output

---

## 8. Production checklist

Voordat je een app "klaar" beschouwt:

| Check | Waarom |
|-------|--------|
| Productie-URL werkt voor alle routes | Anders krijgen gebruikers 404 |
| Env vars staan goed (alle environments) | Anders crashen API routes |
| `.env.local` staat in `.gitignore` | Anders lekken keys op GitHub |
| Eerste feature-branch + PR gedaan | Bewijs dat preview-flow werkt |
| `.cursor/rules/general.mdc` is ingevuld | Anders weet Cursor je conventies niet |
| `AGENTS.md` is ingevuld | Anders weet AI de architectuur niet |
| Build slaagt zonder warnings | Anders begin je met technical debt |
| `404` en `error.tsx` pages bestaan | Voor nette foutmeldingen |

---

## 9. Verder lezen

- **Cursor docs** — `docs.cursor.com` — features, shortcuts, Rules-syntax
- **Vercel docs** — `vercel.com/docs` — alle CLI-commando's, env vars, domains
- **Next.js docs** — `nextjs.org/docs` — App Router, server components, routing
- **AGENTS.md spec** — `agentsmd.org` — community-gedragen format
- **Pro Git** (gratis online) — `git-scm.com/book` — definitieve Git-referentie

---

## Samenvatting

Vandaag heb je geleerd:

- Scaffolden met `npx create-next-app` — alle defaults uitgelegd
- Git init + GitHub push (via `gh` CLI of handmatig)
- Vercel project koppelen — productie + preview URLs gratis erbij
- Vercel CLI — `link`, `env pull/add/rm`, `logs`, `--prod`
- Environment variables — drie environments, `NEXT_PUBLIC_` prefix
- Cursor: chat, plan, build, inline edit, rules, AGENTS.md, background agents
- Feature workflow: plan → branch → build → push → preview
- Top tips voor Cursor power-users

Volgende les bouwen we hier RAG bovenop — een PDF Q&A-app met embeddings.