fix: vercel

2026-06-09 18:02:04 +02:00
parent ee69da1665
commit c023192113
85 changed files with 10266 additions and 3008 deletions
--- a/Les14-Cursor-Vercel-Deploy/Les14-Lesstof.md
+++ b/Les14-Cursor-Vercel-Deploy/Les14-Lesstof.md
@@ -0,0 +1,517 @@
+# Les 13 — Lesstof
+## Externe APIs + Cursor agents + Vercel deploy
+
+**Vak:** AI-Assisted Development
+**Opleiding:** NOVI Hogeschool Utrecht
+**Vorige les:** Les 12 — Tool Calling
+**Volgende les:** Les 14 — Agents
+
+---
+
+## Inhoud
+
+1. [Externe APIs in Next.js](#1-externe-apis-in-nextjs)
+2. [Server- vs client-side fetching](#2-server--vs-client-side-fetching)
+3. [Environment variabelen](#3-environment-variabelen)
+4. [Cursor agents — Composer vs Background](#4-cursor-agents--composer-vs-background)
+5. [Vercel deployments](#5-vercel-deployments)
+6. [Preview deployments per branch](#6-preview-deployments-per-branch)
+7. [GitHub Actions CI](#7-github-actions-ci)
+8. [Branch protection](#8-branch-protection)
+9. [Werkstroom — feature van begin tot productie](#9-werkstroom--feature-van-begin-tot-productie)
+10. [Productie-overwegingen](#10-productie-overwegingen)
+
+---
+
+## 1. Externe APIs in Next.js
+
+Een externe API is een HTTP-endpoint van iemand anders waar je data of functionaliteit kunt ophalen. Voor de meeste apps die je gaat bouwen heb je er minstens één nodig.
+
+### Wat valt eronder
+
+- **Data-APIs** — PokéAPI (Pokemon), Open-Meteo (weer), GitHub API (repos), TMDB (films)
+- **AI-providers** — OpenAI, Anthropic, Tavily (web search)
+- **Payment** — Stripe, Mollie
+- **Auth** — Clerk, Auth0, Supabase Auth
+- **Email** — Resend, Postmark, SendGrid
+
+### Drie smaken qua authenticatie
+
+- **Geen key** — PokéAPI, Open-Meteo. Direct fetchen.
+- **API key in URL of header** — Tavily, TMDB. Key beheren als env-variabele.
+- **OAuth flow** — Google, GitHub. Complexer, vaak via libraries.
+
+### Basis-pattern in Next.js
+
+```typescript
+// Server Component
+async function getPokemon(name: string) {
+  const res = await fetch(`https://pokeapi.co/api/v2/pokemon/${name}`);
+  if (!res.ok) throw new Error("Niet gevonden");
+  return res.json();
+}
+
+export default async function Page({ params }) {
+  const data = await getPokemon(params.name);
+  return <div>{data.name}</div>;
+}
+```
+
+Drie dingen om te onthouden:
+
+- Server Components mogen `async` zijn — `await` direct in component
+- Errors moet je zelf afvangen (`!res.ok`)
+- `fetch` in een Server Component **wordt automatisch gecached** door Next.js
+
+---
+
+## 2. Vier manieren om een externe API te fetchen
+
+Next.js geeft je per fetch-call de keuze hoe je data wilt renderen. Voor 95% van je werk komt het neer op drie server-modes plus client-side. De code verandert minimaal — meestal één optie in je `fetch()`.
+
+### 2.1 Static (build-time)
+
+```typescript
+// app/page.tsx — Server Component
+async function getPokemon() {
+  const res = await fetch("https://pokeapi.co/api/v2/pokemon?limit=151");
+  return res.json();
+}
+```
+
+- Gefetched tijdens `next build`, daarna **HTML voor altijd**
+- Geen server-werk per request → snelste optie
+- Data ververst alleen bij een nieuwe build (= nieuwe deploy)
+- **Goed voor:** marketing-pagina's, blogs, productlijsten, alles dat zelden verandert
+- **Niet voor:** prijzen die per minuut updaten, user-specifieke data
+
+### 2.2 ISR — Incremental Static Regeneration
+
+```typescript
+const res = await fetch(URL, { next: { revalidate: 3600 } });
+```
+
+- Eerste request: zelfde als static (HTML uit cache)
+- Na 3600 seconden: volgende request krijgt nog steeds cache, maar achter de schermen wordt de pagina vernieuwd
+- **Goed voor:** Pokédex detail-pages, een nieuws-feed die niet realtime hoeft, productdetails
+- **De sweet spot tussen snel en redelijk vers**
+
+### 2.3 Dynamic (request-time / SSR)
+
+```typescript
+const res = await fetch(URL, { cache: "no-store" });
+```
+
+- Bij elke request opnieuw gefetched op de server
+- Altijd 100% vers, maar trager (geen cache)
+- **Goed voor:** dashboards met live data, user-specifieke views, anything per-request
+- **Let op cost:** elke request = serverless function call
+
+### 2.4 Client-side (`useEffect`)
+
+```typescript
+"use client";
+import { useEffect, useState } from "react";
+
+export function LivePokemon({ name }) {
+  const [data, setData] = useState(null);
+  useEffect(() => {
+    fetch(`/api/pokemon/${name}`).then((r) => r.json()).then(setData);
+  }, [name]);
+  return data ? <div>{data.name}</div> : <p>Loading...</p>;
+}
+```
+
+- Fetch gebeurt in de browser na hydration
+- Goed voor user-interactie, real-time, infinite scroll
+- **Cruciaal:** API-keys staan **in de browser** als je hier rechtstreeks naar een externe API roept. Alleen voor publieke APIs, of via een eigen `/api/...` proxy-route.
+
+### Spiekbriefje
+
+| Mode | `fetch()` optie | Wanneer |
+|------|----------------|---------|
+| Static | `fetch(URL)` (default) | Data verandert per deploy |
+| ISR | `{ next: { revalidate: N } }` | Data verandert traag |
+| Dynamic | `{ cache: "no-store" }` | Data verandert per request |
+| Client | `useEffect` + fetch | User-interactie / live |
+| Tag-based | `{ next: { tags: ["x"] } }` | Triggered revalidation via `revalidateTag()` |
+
+---
+
+## 3. Environment variabelen — server-only vs client-exposed
+
+### Twee soorten variabelen
+
+| Type | Voorbeeld | Waar beschikbaar | Veiligheid |
+|------|-----------|------------------|------------|
+| Server-only | `OPENAI_API_KEY`, `DATABASE_URL` | Alleen op de server | **Geheim** — nooit zichtbaar voor de browser |
+| Client-exposed | `NEXT_PUBLIC_APP_ENV`, `NEXT_PUBLIC_APP_URL` | Server + client bundle | **Publiek** — iedereen kan ze zien in DevTools |
+
+**Regel:** alles met `NEXT_PUBLIC_` prefix wordt ingebakken in de browser-bundle. Zonder prefix = server-only.
+
+```typescript
+// ✅ Veilig — server-side gebruik
+process.env.OPENAI_API_KEY
+
+// ❌ NOOIT
+"use client";
+const key = process.env.NEXT_PUBLIC_OPENAI_KEY; // staat in de HTML response
+```
+
+### 3.1 Vercel — drie omgevingen, drie scopes
+
+Op Vercel heb je per project drie environments. Bij elke env-var kies je in welke scopes hij wordt geïnjecteerd:
+
+| Scope | Wordt gebruikt bij | URL-patroon |
+|-------|---------------------|-------------|
+| **Production** | Push naar `main` | `je-app.vercel.app` |
+| **Preview** | Push naar elke andere branch | `je-app-git-{branch}-{user}.vercel.app` |
+| **Development** | Lokaal (`pnpm dev`) | `localhost:3000` |
+
+### 3.2 Per-omgeving andere waarden
+
+In **Vercel → Project → Settings → Environment Variables** zet je per variabele drie keer een waarde:
+
+| Var | Production | Preview | Development |
+|-----|------------|---------|-------------|
+| `DATABASE_URL` | productie-DB | staging-DB | lokale DB |
+| `OPENAI_API_KEY` | echte key | test-key (lage limit) | jouw key |
+| `STRIPE_KEY` | `sk_live_...` | `sk_test_...` | `sk_test_...` |
+| `NEXT_PUBLIC_APP_URL` | `je-app.com` | preview-URL | `http://localhost:3000` |
+
+**Hoe in te stellen:** in de UI: Add new → vink alleen de juiste environment(s) aan → Save.
+
+**Belangrijke veiligheidsregels:**
+- Productie-secrets (echte API keys, prod-DB-password): **alleen** Production vinken
+- Preview krijgt een test-variant, anders kunnen experimentele branches je productie raken
+- Development: `vercel env pull` om Vercel's dev-vars naar je `.env.local` te syncen, of zelf invullen
+
+### 3.3 Verandering pakt pas door bij nieuwe build
+
+Bestaande deploys zien een nieuwe env-var niet automatisch. Na het toevoegen of wijzigen: **redeploy** (Deployments → ··· → Redeploy) of push een nieuwe commit.
+
+---
+
+## 4. Cursor agents — Composer vs Background
+
+Cursor heeft twee soorten "agents". Niet hetzelfde, niet uitwisselbaar.
+
+### Composer
+
+- Lokaal in je editor (`Cmd+I` / `Ctrl+I`)
+- **Synchroon** — jij wacht, agent werkt, jij ziet diffs
+- Multi-file edits in één keer
+- Terminal-commands met approval
+- Voor: pair programming, snelle changes, exploreren
+
+### Background Agent
+
+- Runt in **Cursor's cloud sandbox**
+- **Asynchroon** — jij geeft prompt, gaat iets anders doen
+- Maakt zelf een branch + commit + opent PR
+- Kan tests draaien, dependencies installeren
+- Verbonden via Cursor cloud (eenmalige setup)
+- Voor: welomschreven features, parallel werk, PR-prep
+
+### Aanroep
+
+```
+Cursor Composer:    Cmd+I (Mac) of Ctrl+I (Win/Linux)
+Cursor Chat:        Cmd+L (kan switchen naar Agent mode)
+Background Agent:   Cmd+Shift+P → "Open Background Agent"
+                    Of via Slack-integratie
+```
+
+### Mentale model
+
+- **Composer = pair programming.** Jij + AI samen aan dezelfde plek tegelijk.
+- **Background Agent = delegeren.** Je geeft taak, gaat iets anders doen, komt terug als-ie klaar is.
+
+### Wanneer welke
+
+| Scenario | Tool |
+|----------|------|
+| Snel iets aanpassen tijdens coden | Composer |
+| Refactor over 5 files — wil zien wat hij doet | Composer |
+| Onbekend gebied / leren | Composer |
+| Welomschreven feature, can-be-async | Background Agent |
+| Parallel werken aan 3 features | 3x Background Agent |
+| Tijdens vergadering PR voorbereiden | Background Agent |
+
+### Hoe schrijf je een goede Background Agent prompt
+
+Een Background Agent ziet je niet — je moet specifiek zijn.
+
+**Slecht:**
+> "Voeg search toe."
+
+**Goed:**
+> "Maak een nieuwe branch `feature/search`. Voeg een controlled input toe bovenaan `app/page.tsx`. Filter de Pokémon-lijst op naam terwijl gebruiker typt. Case-insensitive. Gebruik Tailwind. Houd het stijl-consistent met bestaande cards. Push de branch en open een PR met titel 'Add search bar' en korte beschrijving in PR body."
+
+Specifiek: bestandsnamen, gedrag, edge cases, output-formaat (branch + PR + titel).
+
+---
+
+## 5. Vercel deployments
+
+Vercel is hosting platform door Next.js team (zelfde bedrijf). Voor Next.js apps de simpelste deploy.
+
+### Eerste deployment
+
+1. Push je repo naar GitHub
+2. `vercel.com` → Add New → Import Git Repository
+3. Kies repo, klik **Deploy**
+4. ~60-90s later: live URL
+
+**Geen config nodig.** Vercel detecteert Next.js automatisch.
+
+### Build settings (als je ze nodig hebt)
+
+- Framework: Next.js (auto)
+- Build command: `pnpm build` (auto)
+- Output directory: `.next` (auto)
+- Install command: `pnpm install`
+- Root directory: alleen aanpassen als app in subfolder zit (monorepo)
+
+### CLI alternatief
+
+```bash
+pnpm i -g vercel
+vercel login
+vercel              # preview deploy van current dir
+vercel --prod       # production deploy
+vercel env pull     # download .env.local van Vercel
+```
+
+---
+
+## 6. Preview deployments per branch
+
+Hier komt de magie. Vercel maakt automatisch een preview deploy voor **elke branch en elke PR**.
+
+### Hoe werkt het
+
+```
+git push origin main                    → Production deploy
+                                          (je-app.vercel.app)
+
+git push origin feature/search          → Preview deploy
+                                          (je-app-git-feature-search-user.vercel.app)
+
+PR open                                 → Vercel comment in PR:
+                                          "🚀 Preview: <URL>"
+```
+
+### Wat krijg je hiermee
+
+- **Reviewers** klikken op de URL in de PR, testen de feature live
+- **Background Agents** maken PR → Vercel zet preview neer → klikbaar
+- **Stakeholders** zien een feature voor merge, niet alleen screenshots
+- **Geen "werkt op mijn laptop"** — alles draait op Vercel infra
+
+### Belangrijk om in te stellen
+
+- **Environment scoping:** preview-deploys mogen geen productie-keys gebruiken — gebruik aparte env vars per scope
+- **Database:** in productie wijs je naar prod-DB, in preview kun je naar test-DB wijzen — meer dan een Vercel-feature, eigen architectuur
+
+### Comment-bot
+
+Vercel installeert een GitHub App. Die plakt een comment op je PR met:
+
+```
+🚀 Preview Deployment: https://...
+✅ Build successful — 1m 23s
+View build log
+```
+
+Per push naar de branch wordt deze comment ge-update.
+
+---
+
+## 7. GitHub Actions CI
+
+Een **CI** (Continuous Integration) check draait automatisch op je code. Minimaal: lint + build.
+
+### Waarom
+
+- Voor merge weet je: code lint clean, types kloppen, build slaagt
+- Cursor Background Agent maakt PR → CI draait → groene check of feedback
+- Voorkomt dat broken code in main komt
+
+### Minimaal workflow
+
+`.github/workflows/ci.yml`:
+
+```yaml
+name: CI
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v3
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm build
+```
+
+### Wat gebeurt er
+
+1. **Trigger:** PR open of update, of push naar `main`
+2. **Runner:** Ubuntu container op GitHub infra
+3. **Stappen:**
+   - Checkout code
+   - Install pnpm + Node 20
+   - Install dependencies
+   - Run lint (faalt op fouten)
+   - Run build (faalt op TypeScript errors)
+4. **Status:** groene check of rode X op de PR
+
+### Tijdsbudget
+
+Voor een kleine Next.js app: 1-2 minuten. Voor grote apps met tests: 3-10 minuten.
+
+### Caching
+
+Met `cache: pnpm` herbruikt GH Actions de node_modules-cache tussen runs — scheelt 60-80% tijd.
+
+---
+
+## 8. Branch protection
+
+Standaard kan iedereen pushen naar main. Voor productie wil je dat niet.
+
+### Branch protection rules (op GitHub)
+
+1. Repo settings → Branches → Add rule
+2. Branch name pattern: `main`
+3. Check: **Require a pull request before merging**
+4. Check: **Require status checks to pass before merging** → select CI workflow
+5. Check: **Do not allow bypassing the above settings**
+
+### Effect
+
+- Niemand kan direct naar `main` pushen — moet via PR
+- PR kan pas merge als CI groen is
+- Force-push naar main geblokkeerd
+- Background Agents werken automatisch via PRs (zo bedoeld)
+
+### Voor solo-projecten
+
+Beetje overkill, maar oefenen is goed. En het voorkomt 'fluitje van een cent' bugs naar main.
+
+---
+
+## 9. Werkstroom — feature van begin tot productie
+
+De volledige flow zoals je 'm in dit vak gebruikt:
+
+```
+1. Idee voor feature
+   ↓
+2. Background Agent prompt (specifiek!)
+   ↓
+3. Cursor opent branch + maakt commits + opent PR
+   ↓
+4. GitHub Actions CI draait — lint + build
+   ↓
+5. Vercel zet preview deploy neer — URL in PR comment
+   ↓
+6. Jij/team reviewt: code-diff + live preview
+   ↓
+7. Eventueel: commentaar in PR, Background Agent retried
+   ↓
+8. Merge PR → main
+   ↓
+9. Vercel productie-deploy is automatisch
+   ↓
+10. Klaar — live op je-app.vercel.app
+```
+
+Tijdsindicatie voor één feature: 10-30 minuten end-to-end (afhankelijk van complexiteit).
+
+### Wat als CI rood is
+
+- Klik op rode X in PR → naar GitHub Actions logs
+- Lees error: lint-error, build-error, of test-failure
+- Twee opties:
+  - **Composer:** open feature branch lokaal, fix met Composer, push
+  - **Background Agent:** nieuwe prompt: "fix de CI error in deze PR — lees de logs en repareer"
+
+### Wat als preview niet werkt
+
+- Open Vercel dashboard → project → Deployments → klik op preview build
+- Build logs lezen
+- Vaak: env-var mist (Vercel preview scope leeg)
+- Of: dependency die op Vercel niet beschikbaar is
+
+---
+
+## 10. Productie-overwegingen
+
+### Costs
+
+| Service | Free tier | Wanneer betalen |
+|---------|-----------|-----------------|
+| **Vercel** | Hobby tier — gratis voor persoonlijk gebruik | Commercieel of >100GB bandwidth |
+| **GitHub Actions** | 2000 min/maand gratis (public repos unlimited) | Bij grote teams of veel runs |
+| **Cursor** | Hobby (gratis), Pro ($20/mnd), Business | Background Agents zitten in Pro/Business |
+| **PokéAPI** | Volledig gratis, geen rate-limit issues | n.v.t. |
+
+### Performance
+
+Vercel doet veel automatisch:
+- Edge CDN voor static assets
+- ISR (Incremental Static Regeneration) voor `revalidate`
+- Image optimization via `next/image`
+- Automatische gzip/brotli
+
+Voor sub-1s page loads: meestal niks doen.
+
+### Observability
+
+- **Vercel Analytics** — page views + Core Web Vitals (gratis tier beperkt)
+- **Vercel Logs** — server-side console.log zichtbaar
+- **Sentry / LogRocket** — externe tools voor error tracking
+- **GitHub Actions logs** — bewaard 90 dagen
+
+### Security
+
+- API keys NOOIT in client (geen `NEXT_PUBLIC_`)
+- `.env.local` in `.gitignore` (vooraf checken!)
+- Rotate keys regelmatig — vooral na PR's van Background Agents
+- Vercel environment scoping om dev/prod te scheiden
+
+### Rollback
+
+Als productie kapot is:
+1. Vercel dashboard → Deployments
+2. Vorige werkende deploy → "Promote to Production"
+3. Klaar, ~10 seconden — geen rebuild nodig
+
+---
+
+## Bronnen
+
+- **Next.js fetching:** https://nextjs.org/docs/app/building-your-application/data-fetching
+- **Next.js caching:** https://nextjs.org/docs/app/building-your-application/caching
+- **PokéAPI:** https://pokeapi.co/
+- **Cursor docs:** https://docs.cursor.com/
+- **Cursor Background Agents:** https://docs.cursor.com/background-agent
+- **Vercel docs:** https://vercel.com/docs
+- **Vercel preview deployments:** https://vercel.com/docs/deployments/preview-deployments
+- **Vercel environment variables:** https://vercel.com/docs/environment-variables
+- **GitHub Actions:** https://docs.github.com/en/actions
+- **GitHub branch protection:** https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches