Documentación

Variables de entorno

Variables de entorno requeridas y opcionales para Motoko Base — base de datos, auth, facturación, email, almacenamiento, analítica, monitoreo e IA.

Abrir enChatGPT Claude Cursor

Motoko Base lee la configuración desde variables de entorno. Copia .env.example a .env o .env.local y completa los valores:

cp .env.example .env

Nunca subas secretos reales. .env* está en gitignore excepto .env.example. Nunca pongas secretos solo de servidor en NEXT_PUBLIC_* — se exponen al navegador.

Las integraciones opcionales fallan de forma suave cuando no están definidas: la app arranca, las rutas no relacionadas siguen funcionando y las páginas de feature muestran un mensaje claro de configuración en lugar de fallar.

Requeridas

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

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

Genera un secreto:

openssl rand -base64 32

Muy recomendadas

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	Required	Purpose
`RESEND_API_KEY`	Recommended	Resend API key for transactional email
`EMAIL_FROM`	Recommended	Sender address, e.g. `Motoko Base <onboarding@resend.dev>` for Resend onboarding tests

Aplicación

Variable	Required	Purpose
`NEXT_PUBLIC_APP_URL`	No	Public app origin for short links (`/r/{slug}`) and password-reset redirects. Falls back to the request origin when unset. Keep aligned with `BETTER_AUTH_URL` in production.

Autenticación

Variable	Required	Purpose
`BETTER_AUTH_SECRET`	Yes	Session and token signing secret
`BETTER_AUTH_URL`	Yes	Canonical auth origin (must match the URL users hit for callbacks)
`BETTER_AUTH_TRUSTED_ORIGINS`	No	Comma-separated extra origins for preview/staging hosts
`GOOGLE_CLIENT_ID`	No	Google OAuth client ID — leave unset to disable Google sign-in
`GOOGLE_CLIENT_SECRET`	No	Google OAuth client secret
`GITHUB_CLIENT_ID`	No	GitHub OAuth app client ID — leave unset to disable GitHub sign-in
`GITHUB_CLIENT_SECRET`	No	GitHub OAuth app client secret

Las callback URLs de OAuth deben coincidir con BETTER_AUTH_URL:

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

Base de datos

Variable	Required	Purpose
`DATABASE_URL`	Yes	PostgreSQL connection string (Supabase or local). Never `NEXT_PUBLIC_*`.

Para Supabase en runtime, prefiere el transaction pooler (a menudo puerto 6543). Si las migraciones fallan por el pooler, apunta temporalmente DATABASE_URL a la conexión directa (a menudo puerto 5432). Consulta src/lib/db/README.md.

Facturación

Variable	Required	Purpose
`BILLING_PROVIDER`	No	Billing provider selection (`polar` in v1). Defaults to `polar`.
`POLAR_ACCESS_TOKEN`	No	Polar Organization Access Token — leave unset to stay on Free
`POLAR_WEBHOOK_SECRET`	No	Webhook secret from Polar → Settings → Webhooks
`POLAR_PRO_MONTHLY_PRODUCT_ID`	No	Pro monthly product ID from Polar Dashboard
`POLAR_PRO_YEARLY_PRODUCT_ID`	No	Pro yearly product ID (optional)
`POLAR_SERVER`	No	`sandbox` or `production` (tokens and products are environment-specific)

Endpoint de webhook: {APP_URL}/api/billing/webhooks/polar

Email

Variable	Required	Purpose
`RESEND_API_KEY`	No*	Resend API key (server-only)
`EMAIL_FROM`	No*	Single sender identity, e.g. `Motoko Base <noreply@yourdomain.com>`

* Ambas hacen falta para la entrega de email. La app arranca sin ellas, pero la verificación de registro no funcionará.

Almacenamiento

Cloudflare R2 impulsa la demo File Storage y las subidas de avatar. Déjalas sin definir para arrancar sin Storage.

Variable	Required	Purpose
`R2_ACCOUNT_ID`	No	Cloudflare account ID (used to build the S3 API endpoint)
`R2_ACCESS_KEY_ID`	No	R2 API token access key
`R2_SECRET_ACCESS_KEY`	No	R2 API token secret
`R2_BUCKET_NAME`	No	Private bucket name. A slash is treated as an object-key prefix: `my-bucket/demo` → bucket `my-bucket`, prefix `demo/`
`R2_PREFIX`	No	Optional explicit object-key prefix (overrides a slash suffix on the bucket name)
`R2_ENDPOINT`	No	Optional S3 API endpoint override (defaults from `R2_ACCOUNT_ID`)

Analítica

PostHog se divide en captura del cliente (project token) y consultas HogQL en el servidor (personal API key).

Variable	Required	Purpose
`NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN`	No	PostHog project API key for client capture
`NEXT_PUBLIC_POSTHOG_HOST`	No	Ingest host (US default: `https://us.i.posthog.com`, EU: `https://eu.i.posthog.com`)
`POSTHOG_PERSONAL_API_KEY`	No	Personal API key with Query Read — used by `/dashboard/analytics`
`POSTHOG_PROJECT_ID`	No	PostHog project ID for HogQL queries
`POSTHOG_HOST`	No	App API host for Query API (US: `https://us.posthog.com`, EU: `https://eu.posthog.com`)

Monitoreo

Variable	Required	Purpose
`NEXT_PUBLIC_SENTRY_DSN`	No	Public Sentry DSN — leave unset to disable monitoring
`SENTRY_AUTH_TOKEN`	No	Auth token for source map upload during `next build`
`SENTRY_ORG`	No	Sentry organization slug
`SENTRY_PROJECT`	No	Sentry project slug

Sentry también se desactiva automáticamente durante next dev (aunque el DSN esté definido) para evitar ruido de listeners de webpack.

IA

Variable	Required	Purpose
`OPENAI_API_KEY`	No	OpenAI or compatible API key — leave unset to disable AI Email demo
`OPENAI_BASE_URL`	No	Optional OpenAI-compatible API base URL
`OPENAI_MODEL`	No	Model ID (defaults to `gpt-4o-mini`)

Referencia rápida por requisito de arranque

Category	Minimal boot	Full feature set
Database	`DATABASE_URL`	`DATABASE_URL`
Authentication	`BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`	+ optional OAuth vars
Email	—	`RESEND_API_KEY`, `EMAIL_FROM`
Billing	—	`POLAR_*` vars
Storage	—	`R2_*` vars
Analytics	—	PostHog vars
Monitoring	—	Sentry vars
AI	—	`OPENAI_API_KEY`

Consulta .env.example para comentarios inline de cada variable.

Siguientes pasos

Configuración — Dónde viven los archivos de config y cómo cambiar navegación, planes de facturación, metadata e integraciones.