MOTOKO BASE

Documentation

Installation

Clonez Motoko Base, configurez les variables d’environnement, lancez les migrations et démarrez le serveur de développement.

Ouvrir dansChatGPT (s’ouvre dans un nouvel onglet)Claude (s’ouvre dans un nouvel onglet)Cursor (s’ouvre dans un nouvel onglet)Clonez Motoko Base, configurez les variables d’environnement, lancez les migrations et démarrez le serveur de développement.

Ce guide vous mène d’un clone frais à une app locale qui tourne. Prévoyez 15–30 minutes pour la première configuration — l’essentiel consiste à créer une base Postgres et à renseigner les variables d’environnement.

Démarrage rapide

Une fois le dépôt sur votre machine :

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

Ouvrez http://localhost:3000. Inscrivez-vous via Sign up, vérifiez votre e-mail, puis ouvrez /dashboard.

Les sections ci-dessous détaillent chaque étape et ce qu’il faut configurer pour que l’app fonctionne de bout en bout.

Version de Node

Motoko Base nécessite Node.js 22 ou plus récent.

node -v

Vous devez voir v22.x.x ou supérieur. Le dépôt fixe cela dans .nvmrc — si vous utilisez nvm :

nvm use

Si Node manque ou est trop ancien, installez le LTS actuel depuis nodejs.org ou via votre gestionnaire de versions.

pnpm

Ce projet utilise pnpm comme gestionnaire de paquets (packageManager est défini dans package.json). N’utilisez pas npm install ni yarn — le lockfile et les scripts sont réservés à pnpm.

Installez pnpm et les dépendances du projet depuis la racine :

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

Le script postinstall exécute fumadocs-mdx pour compiler le contenu de la documentation. Une installation réussie se termine sans erreur.

Variables d’environnement

Copiez le modèle et éditez le nouveau fichier :

cp .env.example .env

Vous pouvez aussi utiliser .env.local — Next.js charge les deux. Ne committez jamais de vrais secrets ; .env* est gitignoré sauf .env.example.

Requis pour un démarrage minimal

Ces trois variables suffisent pour démarrer le serveur de développement et lancer les migrations :

VariablePurpose
DATABASE_URLPostgreSQL connection string (server-only)
BETTER_AUTH_SECRETSigning secret for sessions and tokens
BETTER_AUTH_URLPublic origin for auth callbacks — use http://localhost:3000 locally

Générer un secret :

openssl rand -base64 32

Collez la sortie dans BETTER_AUTH_SECRET dans .env.

Fortement recommandé pour tester l’inscription

La vérification e-mail est obligatoire avant l’accès au dashboard. Sans Resend configuré, vous pouvez démarrer l’app mais vous ne recevrez pas d’e-mails de vérification après l’inscription.

VariablePurpose
RESEND_API_KEYAPI key from Resend
EMAIL_FROMSender address, e.g. Motoko Base <onboarding@resend.dev> for Resend onboarding tests

Intégrations optionnelles

Polar, R2, PostHog, Sentry, OpenAI, Google OAuth et GitHub OAuth sont tous optionnels. L’app échoue soft lorsqu’ils ne sont pas définis — les routes non liées continuent de fonctionner, et les pages de feature affichent un message de configuration clair.

Voir .env.example pour chaque variable et les commentaires inline. Ne placez jamais de secrets serveur sur NEXT_PUBLIC_*.

Base de données

Motoko Base utilise PostgreSQL avec Drizzle ORM. Vous avez besoin d’une instance Postgres en cours d’exécution avant pnpm db:migrate.

Créer une base de données

Choisissez une option :

  • Supabase — créez un projet, copiez la connection string depuis Project Settings → Database
  • Postgres local — créez une base et un utilisateur, puis construisez une URL postgresql://

Pour l’app Next.js au runtime, préférez le transaction pooler de Supabase (souvent le port 6543). Pour les migrations, si le DDL échoue via le pooler, pointez temporairement DATABASE_URL vers la connexion directe (souvent le port 5432).

Définissez l’URL dans .env :

DATABASE_URL=postgresql://...

Lancer les migrations

Depuis la racine du projet :

pnpm db:migrate

Cela applique les migrations SQL de drizzle/migrations/ avec Drizzle Kit. Vous n’avez besoin de relancer qu’après avoir récupéré de nouvelles migrations ou modifié le schéma vous-même (pnpm db:generate puis pnpm db:migrate).

Optionnel : ouvrez Drizzle Studio pour inspecter les tables :

pnpm db:studio

Better Auth

L’authentification est gérée par Better Auth avec un adaptateur Drizzle. Aucun service d’auth supplémentaire n’est requis au-delà de Postgres et des variables ci-dessus.

Pour le développement local, définissez :

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

Gardez BETTER_AUTH_URL aligné avec l’URL que vous ouvrez réellement dans le navigateur — les URI de redirection OAuth et les cookies de session en dépendent.

Google / GitHub sign-in sont optionnels. Laissez GOOGLE_* et GITHUB_* non définis pour démarrer sans eux ; les boutons restent désactivés jusqu’à configuration. Les callback URLs doivent correspondre à BETTER_AUTH_URL :

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

Les routes API d’auth vivent sous /api/auth/*. Les routes protégées du dashboard exigent une session vérifiée.

Première exécution

  1. Démarrez le serveur de développement :

    pnpm dev

  2. Ouvrez http://localhost:3000.

  3. Cliquez sur Sign up, créez un compte avec e-mail et mot de passe.

  4. Vérifiez votre boîte de réception pour l’e-mail de vérification (nécessite Resend). Cliquez sur le lien.

  5. Connectez-vous et ouvrez le Dashboard (/dashboard).

  6. Explorez les pages principales (Settings, Billing) et les démos sous Demos (Link Manager, Storage, AI Email). Les démos qui nécessitent des variables supplémentaires affichent un avis de configuration au lieu de planter.

Avec uniquement les variables minimales, l’auth et le shell du dashboard fonctionnent. Billing reste sur Free, Storage et AI Email affichent des indices de configuration, et analytics/monitoring restent silencieux.