Biz Deploy Vercel — Website sicher mit einem Befehl auf Vercel deployen
Diese Fähigkeit verwandelt ein lokales Projektverzeichnis (React / Next.js / Vite / statisches HTML) in eine Live-URL auf Vercel mit SSL, CDN und Preview-Deployment. Ziel: Solopreneure / KMUs benötigen keine DevOps-Kenntnisse und können ihre Landing Page einfach per Chat mit Claude deployen.
Prinzip: Frage den Benutzer nicht nach Dingen, die Claude selbst prüfen kann. Erkenne das Framework automatisch, generiere
vercel.jsonbei Bedarf und halte nur bei echten manuellen Hürden an (Browser-Login, Custom-Domain-DNS).
Wann verwenden
Der Benutzer möchte:
- Eine Landing Page / Website auf eine Live-URL bringen, um sie zu teilen / testen / für Werbung zu nutzen
- Ein Projekt nach Code-Änderungen neu deployen
- Vercel zum ersten Mal für ein neues Repository einrichten
- Eine benutzerdefinierte Domain auf Vercel verweisen
Wann NICHT verwenden
- Nur lokal bauen, noch nicht veröffentlichen → überspringen, stattdessen
npm run build/next devverwenden. - Deployment auf Netlify / Cloudflare Pages / AWS erforderlich → dieses Skill ist auf Vercel spezialisiert.
- Komplexes CI/CD mit benutzerdefinierten GitHub Actions erforderlich → dieses Skill immer noch zur Projekterstellung verwenden, den benutzerdefinierten Workflow aber selbst konfigurieren.
- Backend mit Node.js und vollständigem Server-Status (Websockets, Long Polling) erforderlich → Vercel Serverless ist nicht geeignet, stattdessen Railway / Fly.io verwenden.
Vom Benutzer erhaltene Ausgabe
- Live-URL im Format
https://<project>.vercel.app(Produktion) oder Preview-URL. - Inspect-URL im Format
https://vercel.com/<account>/<project>/<deployment-id>zum Anzeigen von Logs. - Verknüpftes Projekt in
.vercel/project.json(in.gitignore) – für nachfolgende Deployments reichtvercel --prod. - Wenn der Benutzer eine benutzerdefinierte Domain wünscht → spezifische DNS-Anweisungen (A-Record / CNAME).
6-Schritte-Workflow
Schritt 1 — Preflight: Prüfe Vercel CLI / MCP
Führe scripts/check_vercel.sh (oder entsprechende Inline-Befehle) aus, um den Status dieser drei Dinge zu ermitteln:
| Was ist zu prüfen | Befehl | Erwartetes Ergebnis |
|---|---|---|
| Node.js | node --version | v18+ oder v20+ |
| Vercel CLI | vercel --version | Version wird zurückgegeben (v32+) |
| Vercel Auth | vercel whoami | Benutzername wird zurückgegeben |
Wenn Node.js fehlt:
- macOS:
brew install nodeempfehlen oder https://nodejs.org herunterladen - Windows: Anleitung zum Herunterladen des
.msi-Installers von https://nodejs.org/en/download/ - Linux:
nvm install --ltsoder Paketmanager. - Skill anhalten, auf Rückmeldung des Benutzers nach erfolgreicher Installation warten.
Wenn Vercel CLI fehlt:
- Erkenne den verwendeten Paketmanager (prüfe
pnpm,yarn,npmin dieser Reihenfolge oder lese die Lock-Datei des Projekts). - Global installieren:
pnpm add -g vercel(falls der Benutzer pnpm verwendet)npm install -g vercel(Standard)
- Mit
vercel --versionerneut überprüfen.
Wenn Vercel CLI vorhanden, aber nicht authentifiziert (vercel whoami meldet Fehler):
- Führe
vercel loginaus – dieser Befehl öffnet den Browser, der Benutzer muss die Authentifizierung bestätigen. Dies ist eine manuelle Hürde, die nicht übersprungen werden kann. - Teile dem Benutzer mit: "Ich habe
vercel loginausgeführt. Öffne den Browser, klicke auf Bestätigen, um dich zu authentifizieren. Wenn du fertig bist, tippe 'ok', damit ich fortfahren kann." - Anhalten, auf Rückmeldung des Benutzers warten.
Wenn der Benutzer angibt, Vercel MCP zu verwenden:
- Prüfe den MCP-Server, indem du die verfügbaren MCP-Tools auflistest (Tools mit Präfix
mcp__vercel__*). - Bevorzuge bei MCP dennoch die CLI für das eigentliche Deployment (CLI ist stabiler für Datei-Uploads). Verwende MCP, um bei Bedarf nach dem Deployment Projekte / Domains / Umgebungsvariablen abzufragen.
- Wenn der Benutzer zwingend MCP verwenden möchte: Folge der Dokumentation unter https://vercel.com/docs/mcp zur Authentifizierung und verwende dann die entsprechenden MCP-Tools.
Schritt 2 — Framework erkennen + Projektstruktur analysieren
Lese die Dateien im Projektstammverzeichnis, um das Framework zu identifizieren:
| Datei | Framework |
|---|---|
next.config.js / next.config.mjs / next.config.ts | Next.js |
vite.config.js / vite.config.ts | Vite (React/Vue/Svelte) |
package.json mit "react-scripts" | Create React App |
package.json mit "astro" | Astro |
package.json mit "@remix-run/dev" | Remix |
Nur index.html + Assets, kein package.json | Statisches HTML |
package.json vorhanden, aber keine Übereinstimmung mit obigen Mustern | Frage den Benutzer nach dem Framework oder überlasse Vercel die automatische Erkennung |
Notiere zusätzlich:
- Build-Befehl aus
package.json(scripts.build) - Ausgabeverzeichnis (Next:
.next, Vite:dist, CRA:build, statisch:.) - Erforderliche Node-Version (aus
engines.nodeoder.nvmrc)
→ Lese die entsprechende Referenz:
- React/Vite →
references/react-vite.md - Next.js →
references/nextjs.md - Statisches HTML →
references/static-html.md
Schritt 3 — vercel.json generieren (falls erforderlich)
Next.js: Vercel erkennt das Framework vollständig automatisch, keine vercel.json erforderlich, es sei denn, benutzerdefinierte Header / Weiterleitungen sind gewünscht.
Vite / CRA (SPA-Routing): vercel.json mit Rewrite aller Routen auf index.html erforderlich, damit clientseitiges Routing funktioniert:
{
"rewrites": [
{ "source": "/(.*)", "destination": "/index.html" }
]
}
Statisches HTML: In der Regel nicht erforderlich. Wenn die Site mehrere Seiten hat (thank-you.html, privacy.html), ist kein Rewrite nötig. Wenn nur index.html + JS-Router vorhanden ist, ist ein Rewrite wie bei SPA erforderlich.
Sicherheitsheader (empfohlen für die Produktion):
{
"headers": [
{
"source": "/(.*)",
"headers": [
{ "key": "X-Content-Type-Options", "value": "nosniff" },
{ "key": "X-Frame-Options", "value": "DENY" },
{ "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
]
}
]
}
Regel: Erstelle vercel.json nur, wenn der Benutzer es wirklich benötigt. Eine unnötige Datei zu erstellen, bedeutet Rauschen im Repository.
Schritt 4 — Pre-Deployment-Checkliste
Überprüfe vor dem Ausführen von vercel Folgendes:
-
.gitignoreenthält.vercel/,node_modules/,.env*(Geheimnisse DÜRFEN NICHT committed werden) - Dateipfade im Code sind alle kleingeschrieben + relativ (Linux unterscheidet Groß-/Kleinschreibung)
- Keine hartcodierten
localhost-URLs - Externe Skripte/Stylesheets verwenden
https:// - Bei Next.js mit Umgebungsvariablen → Liste der zu setzenden Variablen vorbereitet
- Bei vorhandenem
package.json→npm install(oder entsprechend) funktioniert lokal
Wenn offensichtliche Probleme erkannt werden (z. B. hartcodiertes localhost in HTML), korrigiere sie zuerst, bevor du deployst.
Schritt 5 — Deployment
Erstmaliges Deployment eines Projekts (kein .vercel/project.json vorhanden):
vercel --prod --yes
Die Option --yes akzeptiert alle Standardeinstellungen aus der Framework-Autoerkennung. Vercel wird:
- Den Bereich auswählen (bei
--yesautomatisch das Benutzerkonto) - Das Framework-Preset erkennen
- Build-Befehl und Ausgabeverzeichnis festlegen
- Code pushen, bauen und deployen
Wenn ein benutzerdefinierter Projektname erforderlich ist oder der Benutzer eine Verknüpfung mit einem vorhandenen Projekt wünscht:
vercel link # Mit vorhandenem Projekt verknüpfen (interaktiv)
vercel --prod # Nach der Verknüpfung deployen
Preview (Nicht-Produktion) deployen:
vercel
→ Gibt eine Preview-URL im Format https://<project>-<hash>.vercel.app zurück, die zum Testen vor der Produktionsfreigabe verwendet werden kann.
Erneutes Deployment (Projekt bereits verknüpft):
vercel --prod
Ausgabe erfassen – parse stdout, um Folgendes zu erhalten:
Production: https://<project>.vercel.appInspect: https://vercel.com/...
Teile dem Benutzer diese beiden URLs sofort mit.
Schritt 6 — Überprüfung + Bericht
Nach erfolgreichem Deployment:
- HTTP-Prüfung der Live-URL mit
curl -I https://<project>.vercel.app– überprüfe Status 200 + aktives SSL. - Bericht an den Benutzer im folgenden Format:
## ✅ Deployment erfolgreich
**Live-URL**: https://<project>.vercel.app
**Inspect / Logs**: https://vercel.com/<account>/<project>/<deployment-id>
**Framework**: <Next.js | Vite | CRA | Statisches HTML>
**Build-Zeit**: <Xs>
### Nächstes Deployment
Führe einfach aus: `vercel --prod`
### Optionen
- Benutzerdefinierte Domain einrichten → sag mir `setup domain <yourdomain.com>`
- Umgebungsvariablen einrichten → sag mir `add env <KEY>`
- Logs ansehen → `vercel logs`
- Wenn der Benutzer eine benutzerdefinierte Domain wünscht → lese
references/domains.mdund gebe DNS-Anweisungen.
Randfälle + Wiederherstellung
Build auf Vercel fehlgeschlagen, aber lokal funktioniert es
Häufige Ursachen:
- Groß-/Kleinschreibung:
import './Components/Header'funktioniert lokal auf dem Mac, schlägt aber auf Linux fehl, wenn das tatsächliche Verzeichniscomponentsheißt. Korrektur: Benenne es mit der korrekten Schreibweise um. - Fehlende Abhängigkeit: Ein Paket befindet sich in
devDependencies, wird aber zur Laufzeit benötigt → verschiebe es independencies. - Node-Version nicht kompatibel: Füge
"engines": { "node": "20.x" }inpackage.jsonoder eine.nvmrc-Datei hinzu.
→ Hole das Log mit vercel logs <deployment-url>, lese es, korrigiere den Fehler und deploye erneut.
Projekt wurde mit falschem Konto / falschem Projekt verknüpft
rm -rf .vercel/ und dann vercel --prod --yes erneut ausführen. Oder mit vercel link das richtige Projekt auswählen.
Umgebungsvariablen für die Produktion
vercel env add <KEY> production
# Wert bei Eingabeaufforderung einfügen
vercel env pull .env.production.local # Bei Bedarf lokal abrufen
Vermeide es, .env*-Dateien zu committed. Füge sie zu .gitignore hinzu, falls nicht bereits vorhanden.
Authentifizierung abgelaufen
Das CLI-Token kann ablaufen. Wenn vercel whoami einen Unauthorized-Fehler meldet → führe vercel login erneut aus.
Detailierte Framework-Referenzen
Lese die Referenz, die zum Framework des Projekts passt:
| Framework | Referenz |
|---|---|
| Next.js (App / Pages Router) | references/nextjs.md |
| React (Vite / CRA) | references/react-vite.md |
| Statisches HTML | references/static-html.md |
| Benutzerdefinierte Domain + DNS | references/domains.md |
| Fehler & Fehlerbehebung | references/troubleshooting.md |
Ursprüngliche Referenzen
- Vercel CLI-Dokumentation: https://vercel.com/docs/cli
- Vercel Build-Konfiguration: https://vercel.com/docs/projects/project-configuration
- Vercel Limits (kostenloser Tarif): https://vercel.com/docs/limits
- Status-Seite: https://www.vercel-status.com