Dokumentation

Installation

Motoko Base klonen, Umgebungsvariablen konfigurieren, Migrationen ausführen und den Dev-Server starten.

Dieser Leitfaden führt Sie von einem frischen Clone zu einer laufenden lokalen App. Rechnen Sie beim ersten Setup mit 15–30 Minuten — der Großteil entfällt auf das Anlegen einer Postgres-Datenbank und das Ausfüllen der Env-Vars.

Schnellstart

Nachdem Sie das Repository auf Ihrer Maschine haben:

git clone <repository-url> motoko-base
cd motoko-base
pnpm install
cp .env.example .env
pnpm db:migrate
pnpm dev

Öffnen Sie http://localhost:3000. Registrieren Sie sich unter Sign up, verifizieren Sie Ihre E-Mail und öffnen Sie dann /dashboard.

Die Abschnitte unten erklären jeden Schritt und was Sie konfigurieren müssen, bevor die App End-to-End funktioniert.

Node-Version

Motoko Base erfordert Node.js 22 oder neuer.

node -v

Sie sollten v22.x.x oder höher sehen. Das Repo pinnt das in .nvmrc — wenn Sie nvm nutzen:

nvm use

Fehlt Node oder ist es zu alt, installieren Sie das aktuelle LTS von nodejs.org oder über Ihren Versionsmanager.

pnpm

Dieses Projekt verwendet pnpm als Paketmanager (packageManager ist in package.json gesetzt). Verwenden Sie nicht npm install oder yarn — Lockfile und Scripts sind pnpm-only.

Installieren Sie pnpm und die Projektabhängigkeiten vom Projektroot aus:

corepack enable
corepack prepare pnpm@latest --activate
pnpm install

Das postinstall-Script führt fumadocs-mdx aus, um Dokumentationsinhalte zu kompilieren. Eine erfolgreiche Installation endet ohne Fehler.

Umgebungsvariablen

Kopieren Sie die Vorlage und bearbeiten Sie die neue Datei:

cp .env.example .env

Sie können auch .env.local verwenden — Next.js lädt beides. Committen Sie niemals echte Secrets; .env* ist gitignored außer .env.example.

Erforderlich für den Minimal-Boot

Diese drei Variablen reichen aus, um den Dev-Server zu starten und Migrationen auszuführen:

Variable	Purpose
`DATABASE_URL`	PostgreSQL connection string (server-only)
`BETTER_AUTH_SECRET`	Signing secret for sessions and tokens
`BETTER_AUTH_URL`	Public origin for auth callbacks — use `http://localhost:3000` locally

Secret erzeugen:

openssl rand -base64 32

Fügen Sie die Ausgabe in BETTER_AUTH_SECRET in .env ein.

Stark empfohlen zum Testen der Registrierung

E-Mail-Verifizierung ist erforderlich, bevor der Dashboard-Zugang möglich ist. Ohne konfiguriertes Resend können Sie die App starten, erhalten nach der Registrierung aber keine Verifizierungs-E-Mails.

Variable	Purpose
`RESEND_API_KEY`	API key from Resend
`EMAIL_FROM`	Sender address, e.g. `Motoko Base <onboarding@resend.dev>` for Resend onboarding tests

Optionale Integrationen

Polar, R2, PostHog, Sentry, OpenAI, Google OAuth und GitHub OAuth sind alle optional. Die App soft-fails, wenn sie nicht gesetzt sind — unabhängige Routen bleiben funktionsfähig, und Feature-Seiten zeigen eine klare Konfigurationsmeldung.

Siehe .env.example für jede Variable und Inline-Kommentare. Legen Sie Server-Secrets niemals auf NEXT_PUBLIC_*.

Datenbank

Motoko Base verwendet PostgreSQL mit Drizzle ORM. Sie brauchen eine laufende Postgres-Instanz vor pnpm db:migrate.

Eine Datenbank anlegen

Wählen Sie eine Option:

Supabase — Projekt anlegen, Connection String unter Project Settings → Database kopieren
Lokales Postgres — Datenbank und User anlegen, dann eine postgresql://-URL bauen

Für die Next.js-App zur Laufzeit bevorzugen Sie Supabases Transaction Pooler (oft Port 6543). Für Migrationen: schlägt DDL über den Pooler fehl, zeigen Sie DATABASE_URL vorübergehend auf die direkte Verbindung (oft Port 5432).

URL in .env setzen:

DATABASE_URL=postgresql://...

Migrationen ausführen

Vom Projektroot aus:

pnpm db:migrate

Das wendet SQL-Migrationen aus drizzle/migrations/ mit Drizzle Kit an. Sie müssen nur erneut ausführen, nachdem Sie neue Migrationen gezogen oder das Schema selbst geändert haben (pnpm db:generate, dann pnpm db:migrate).

Optional: Drizzle Studio öffnen, um Tabellen zu inspizieren:

pnpm db:studio

Better Auth

Authentifizierung übernimmt Better Auth mit einem Drizzle-Adapter. Es ist kein zusätzlicher Auth-Service nötig — Postgres und die Env-Vars oben reichen.

Für die lokale Entwicklung setzen:

BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000

Halten Sie BETTER_AUTH_URL an der URL ausgerichtet, die Sie im Browser öffnen — OAuth-Redirect-URIs und Session-Cookies hängen davon ab.

Google-/GitHub-Sign-in sind optional. Lassen Sie GOOGLE_* und GITHUB_* ungesetzt, um ohne sie zu booten; die Buttons bleiben deaktiviert, bis sie konfiguriert sind. Callback-URLs müssen zu BETTER_AUTH_URL passen:

Google: {BETTER_AUTH_URL}/api/auth/callback/google
GitHub: {BETTER_AUTH_URL}/api/auth/callback/github

Auth-API-Routen liegen unter /api/auth/*. Geschützte Dashboard-Routen erfordern eine verifizierte Session.

Erster Start

Dev-Server starten:
```
pnpm dev
```
http://localhost:3000 öffnen.
Auf Sign up klicken, Konto mit E-Mail und Passwort anlegen.
Posteingang auf die Verifizierungs-E-Mail prüfen (erfordert Resend). Link anklicken.
Anmelden und Dashboard (/dashboard) öffnen.
Kernseiten (Settings, Billing) und Demo-Features unter Demos (Link Manager, Storage, AI Email) erkunden. Demos, die Extra-Env-Vars brauchen, zeigen einen Konfigurationshinweis statt abzustürzen.

Mit nur den minimalen Env-Vars funktionieren Auth und die Dashboard-Shell. Billing bleibt auf Free, Storage und AI Email zeigen Setup-Hinweise, Analytics/Monitoring bleiben still.