Diese Anleitung führt dich durch den gesamten Einrichtungsprozess — vom Klonen des Repositories bis hin zum laufenden App im Browser. Geschätzte Zeit: 10–15 Minuten.
Voraussetzungen
Überprüfe, ob die erforderlichen Tools installiert sind, bevor du fortfährst.
# Node.js-Version prüfen (erfordert v20.x)
node --version
# pnpm-Version prüfen (erfordert v9.x)
pnpm --version
# Git prüfen
git --version
Falls du Node.js installieren musst, empfehlen wir nvm:
nvm install 20
nvm use 20
pnpm global installieren:
npm install -g pnpm
Einrichtungsschritte
1
Repository klonen
Klone das Kit-Repository auf deinen lokalen Rechner:
bash
git clone <your-repository-url> my-saas-app
cd my-saas-app
Ersetze
<your-repository-url> durch die URL, die du nach dem Kauf erhalten hast.2
Abhängigkeiten installieren
Installiere alle Projektabhängigkeiten mit pnpm:
bash
pnpm install
pnpm ist deutlich schneller als npm und benötigt durch Content-Addressable Storage weniger Speicherplatz. Falls eine Abfrage zur pnpm-Version erscheint, bestätige sie, um fortzufahren.
3
Umgebungsvariablen einrichten
Kopiere die Beispiel-Umgebungsdatei, um deine lokale Konfiguration zu erstellen:
bash
cp apps/boilerplate/.env.example apps/boilerplate/.env.local
Committe
.env.local niemals in die Versionskontrolle. Sie enthält sensible API-Schlüssel und Geheimnisse. Die Datei ist bereits in .gitignore aufgeführt.Für eine minimale Einrichtung benötigst du nur die Datenbank-URL. Öffne
apps/boilerplate/.env.local und konfiguriere:bash
# Erforderlich: Deine App-URL
NEXT_PUBLIC_APP_URL=http://localhost:3000
# Erforderlich: Datenbank (siehe nächsten Schritt für Optionen)
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/nextjs_dev
DIRECT_URL=postgresql://postgres:postgres@localhost:5432/nextjs_dev
Alle anderen Dienste (Clerk, Lemon Squeezy, Resend usw.) können später konfiguriert werden. Kit funktioniert im Entwicklungsmodus auch ohne sie.
4
Datenbank einrichten
Du hast zwei Möglichkeiten, PostgreSQL zu betreiben.
Der einfachste Weg, eine lokale Datenbank zu betreiben. Erfordert Docker Desktop.
# PostgreSQL im Hintergrund starten
pnpm db:up
Damit wird ein PostgreSQL-15-Container mit folgenden Standardwerten gestartet:
version: '3.8'
services:
postgres:
image: postgres:15-alpine
container_name: nextjs-boilerplate-db
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: nextjs_dev
ports:
- '5432:5432'
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U postgres']
interval: 5s
timeout: 5s
retries: 5
Die Datenbank-URL ist in
apps/boilerplate/.env.example für dieses Setup bereits vorkonfiguriert:DATABASE_URL=postgresql://postgres:postgres@localhost:5432/nextjs_dev
DIRECT_URL=postgresql://postgres:postgres@localhost:5432/nextjs_dev
Jetzt den Prisma-Client generieren und das Schema in die Datenbank übertragen:
bash
cd apps/boilerplate && npx prisma generate
cd apps/boilerplate && npx prisma db push
5
Dev-Server starten
Den Entwicklungsserver starten:
bash
pnpm dev:boilerplate
Öffne http://localhost:3000 in deinem Browser. Du solltest die Kit-Startseite sehen.
Falls du Clerk noch nicht eingerichtet hast, verwende stattdessen
pnpm dev:no-clerk. Damit wird die App mit einem Mock-Authentifizierungssystem gestartet, sodass du das Dashboard sofort erkunden kannst.Einrichtung überprüfen
Bestätige nach dem Start des Dev-Servers, dass alles funktioniert:
- Startseite lädt — Besuche http://localhost:3000 und sieh die Marketing-Seite
- Health-Endpunkt — Besuche http://localhost:3000/api/health und bestätige eine JSON-Antwort
- Dashboard-Zugriff — Falls du
pnpm dev:no-clerkverwendest, navigiere zu http://localhost:3000/dashboard, um das Dashboard mit dem Mock-Benutzer zu sehen
Entwicklung ohne Clerk
Kit enthält einen No-Clerk-Modus für die Entwicklung ohne Authentifizierungs-Zugangsdaten. Das ist nützlich, wenn du das Dashboard erkunden, UI-Komponenten testen oder an Features arbeiten möchtest, bevor du Clerk einrichtest.
Starte die Boilerplate-App im No-Clerk-Modus:
bash
pnpm dev:no-clerk
In diesem Modus verwendet Kit ein Mock-Authentifizierungssystem mit einem Testbenutzer:
src/lib/auth/config.ts
export function shouldUseClerk(): boolean {
// Priority 0: Demo Mode always bypasses Clerk (even in production)
// This allows public demo deployments without real auth
if (process.env.NEXT_PUBLIC_DEMO_MODE === 'true') {
return false
}
// Priority 1: Never use test auth in production (safety first)
if (isProduction()) {
return true
}
// Priority 2: Use test auth in test environments (explicit disable)
if (isTestEnvironment()) {
return false
}
// Priority 3: In development, use Clerk if credentials are available
return hasClerkCredentials()
}
Der Mock-Benutzer ist automatisch angemeldet und hat Zugriff auf alle Dashboard-Routen. Wenn du bereit bist, echte Authentifizierung einzurichten, sieh dir die Authentifizierungsübersicht an.
Verfügbare Skripte
Dies sind die wichtigsten Skripte, die du während der Entwicklung verwenden wirst. Alle Skripte werden vom Monorepo-Root aus ausgeführt:
| Skript | Beschreibung |
|---|---|
pnpm dev:boilerplate | Boilerplate-Dev-Server mit Hot Reload starten (Turbopack) |
pnpm dev:no-clerk | Boilerplate-Dev-Server ohne Clerk-Authentifizierung starten |
pnpm build | Alle Pakete und Apps bauen |
pnpm build:boilerplate | Nur die Boilerplate-App bauen |
pnpm lint | ESLint über alle Pakete ausführen |
pnpm typecheck | TypeScript-Typprüfung über alle Pakete ausführen |
pnpm format | Code mit Prettier formatieren |
pnpm validate | Typecheck + Lint + Format-Prüfung über alle Pakete ausführen |
pnpm test:unit | Alle Unit-Tests mit Vitest ausführen |
pnpm test:e2e:smoke | Smoke-E2E-Tests mit Playwright ausführen |
pnpm db:up | PostgreSQL über Docker Compose starten |
pnpm db:down | PostgreSQL-Container stoppen |
pnpm db:reset | Datenbank zurücksetzen (löschen + neu erstellen + migrieren) |
pnpm db:studio | Prisma Studio öffnen (visueller Datenbank-Browser) |
pnpm deploy | Qualitätsprüfungen ausführen und auf Vercel deployen |
Für Prisma-Befehle ohne Root-Aliase verwende
cd apps/boilerplate && vor dem Befehl:bash
cd apps/boilerplate && npx prisma generate
cd apps/boilerplate && npx prisma migrate dev --name <name>