Documentación

Instalación

Clona Motoko Base, configura las variables de entorno, ejecuta migraciones e inicia el servidor de desarrollo.

Esta guía te lleva desde un clon fresco hasta una app local en marcha. Reserva 15–30 minutos en la primera configuración — la mayor parte es crear una base de datos Postgres y completar las variables de entorno.

Inicio rápido

Cuando tengas el repositorio en tu máquina:

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

Abre http://localhost:3000. Regístrate en Sign up, verifica tu email y luego abre /dashboard.

Las secciones siguientes explican cada paso y qué configurar para que la app funcione de extremo a extremo.

Versión de Node

Motoko Base requiere Node.js 22 o superior.

node -v

Deberías ver v22.x.x o superior. El repo fija esto en .nvmrc — si usas nvm:

nvm use

Si Node falta o es demasiado antiguo, instala el LTS actual desde nodejs.org o con tu gestor de versiones.

pnpm

Este proyecto usa pnpm como gestor de paquetes (packageManager está definido en package.json). No uses npm install ni yarn — el lockfile y los scripts son solo de pnpm.

Instala pnpm y las dependencias del proyecto desde la raíz:

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

El script postinstall ejecuta fumadocs-mdx para compilar el contenido de la documentación. Una instalación correcta termina sin errores.

Variables de entorno

Copia la plantilla y edita el archivo nuevo:

cp .env.example .env

También puedes usar .env.local — Next.js carga ambos. Nunca subas secretos reales; .env* está en gitignore excepto .env.example.

Necesarias para un arranque mínimo

Estas tres variables bastan para iniciar el servidor de desarrollo y ejecutar migraciones:

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

Genera un secreto:

openssl rand -base64 32

Pega el resultado en BETTER_AUTH_SECRET en .env.

Muy recomendadas para probar el registro

La verificación de email es obligatoria antes de acceder al dashboard. Sin Resend configurado, puedes arrancar la app pero no recibirás emails de verificación tras el registro.

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

Integraciones opcionales

Polar, R2, PostHog, Sentry, OpenAI, Google OAuth y GitHub OAuth son opcionales. La app falla de forma suave cuando no están definidas — las rutas no relacionadas siguen funcionando y las páginas de feature muestran un mensaje claro de configuración.

Consulta .env.example para cada variable y sus comentarios. Nunca pongas secretos de servidor en NEXT_PUBLIC_*.

Base de datos

Motoko Base usa PostgreSQL con Drizzle ORM. Necesitas una instancia de Postgres en marcha antes de pnpm db:migrate.

Crear una base de datos

Elige una opción:

Supabase — crea un proyecto y copia la connection string desde Project Settings → Database
Postgres local — crea una base y un usuario, luego construye una URL postgresql://

Para la app Next.js en runtime, prefiere el transaction pooler de Supabase (a menudo puerto 6543). Para migraciones, si el DDL falla por el pooler, apunta temporalmente DATABASE_URL a la conexión directa (a menudo puerto 5432).

Define la URL en .env:

DATABASE_URL=postgresql://...

Ejecutar migraciones

Desde la raíz del proyecto:

pnpm db:migrate

Esto aplica las migraciones SQL de drizzle/migrations/ con Drizzle Kit. Solo necesitas volver a ejecutarlas tras traer migraciones nuevas o cambiar el esquema tú mismo (pnpm db:generate y luego pnpm db:migrate).

Opcional: abre Drizzle Studio para inspeccionar tablas:

pnpm db:studio

Better Auth

La autenticación la gestiona Better Auth con un adaptador Drizzle. No hace falta un servicio de auth aparte más allá de Postgres y las variables anteriores.

Para desarrollo local, define:

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

Mantén BETTER_AUTH_URL alineado con la URL que abres en el navegador — las URI de redirección OAuth y las cookies de sesión dependen de ella.

Google / GitHub sign-in son opcionales. Deja GOOGLE_* y GITHUB_* sin definir para arrancar sin ellos; los botones permanecen deshabilitados hasta configurarlos. Las callback URLs deben coincidir con BETTER_AUTH_URL:

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

Las rutas de la API de auth viven en /api/auth/*. Las rutas protegidas del dashboard requieren una sesión verificada.

Primera ejecución

Inicia el servidor de desarrollo:
```
pnpm dev
```
Abre http://localhost:3000.
Haz clic en Sign up, crea una cuenta con email y contraseña.
Revisa tu bandeja de entrada para el email de verificación (requiere Resend). Haz clic en el enlace.
Inicia sesión y abre Dashboard (/dashboard).
Explora las páginas principales (Settings, Billing) y las demos bajo Demos (Link Manager, Storage, AI Email). Las demos que necesitan variables extra muestran un aviso de configuración en lugar de fallar.

Con solo las variables mínimas, auth y el shell del dashboard funcionan. Billing permanece en Free, Storage y AI Email muestran pistas de configuración, y analytics/monitoring se quedan en silencio.