Documentação

Variáveis de ambiente

Variáveis de ambiente obrigatórias e opcionais do Motoko Base — banco de dados, auth, cobrança, e-mail, armazenamento, analytics, monitoramento e IA.

Abrir emChatGPT Claude Cursor

O Motoko Base lê a configuração a partir de variáveis de ambiente. Copie .env.example para .env ou .env.local e preencha os valores:

cp .env.example .env

Nunca faça commit de segredos reais. .env* está no gitignore, exceto .env.example. Nunca coloque segredos só de servidor em NEXT_PUBLIC_* — eles são expostos ao navegador.

Integrações opcionais falham de forma suave quando não definidas: o app sobe, rotas não relacionadas continuam funcionando e as páginas de feature mostram uma mensagem clara de configuração em vez de quebrar.

Obrigatórias

Essas três variáveis bastam para iniciar o servidor de desenvolvimento e rodar migrations:

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

Gere um segredo:

openssl rand -base64 32

Fortemente recomendadas

A verificação de e-mail é obrigatória antes do acesso ao dashboard. Sem o Resend configurado, você consegue iniciar o app, mas não receberá e-mails de verificação após o cadastro.

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

Aplicação

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.

Autenticação

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

As callback URLs do OAuth devem corresponder a BETTER_AUTH_URL:

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

Banco de dados

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

Para o Supabase em runtime, prefira o transaction pooler (muitas vezes a porta 6543). Se as migrations falharem pelo pooler, aponte temporariamente DATABASE_URL para a conexão direta (muitas vezes a porta 5432). Veja src/lib/db/README.md.

Cobrança

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

E-mail

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 são necessárias para a entrega de e-mail. O app sobe sem elas, mas a verificação de cadastro não funcionará.

Armazenamento

O Cloudflare R2 alimenta a demo File Storage e os uploads de avatar. Deixe indefinido para iniciar sem 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`)

Analytics

O PostHog se divide em captura no cliente (project token) e consultas HogQL no 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`)

Monitoramento

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

O Sentry também é desativado automaticamente durante next dev (mesmo com DSN definido) para evitar ruído de listeners do 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`)

Referência rápida por requisito de boot

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`

Veja .env.example para comentários inline de cada variável.

Próximos passos

Configuração — Onde os arquivos de config ficam e como alterar navegação, planos de cobrança, metadata e integrações.