MOTOKO BASE

Documentação

Instalação

Clone o Motoko Base, configure as variáveis de ambiente, rode as migrations e inicie o servidor de desenvolvimento.

Abrir emChatGPT (abre em uma nova aba)Claude (abre em uma nova aba)Cursor (abre em uma nova aba)Clone o Motoko Base, configure as variáveis de ambiente, rode as migrations e inicie o servidor de desenvolvimento.

Este guia leva você de um clone novo até um app local em execução. Reserve 15–30 minutos na primeira configuração — a maior parte é criar um banco Postgres e preencher as variáveis de ambiente.

Início rápido

Depois de ter o repositório na sua máquina:

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

Abra http://localhost:3000. Cadastre-se em Sign up, verifique seu e-mail e depois abra /dashboard.

As seções abaixo explicam cada passo e o que configurar para o app funcionar de ponta a ponta.

Versão do Node

O Motoko Base exige Node.js 22 ou mais recente.

node -v

Você deve ver v22.x.x ou superior. O repositório fixa isso em .nvmrc — se você usa nvm:

nvm use

Se o Node estiver ausente ou antigo demais, instale o LTS atual em nodejs.org ou pelo seu gerenciador de versões.

pnpm

Este projeto usa pnpm como gerenciador de pacotes (packageManager está definido em package.json). Não use npm install nem yarn — o lockfile e os scripts são exclusivos do pnpm.

Instale o pnpm e as dependências do projeto a partir da raiz:

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

O script postinstall executa fumadocs-mdx para compilar o conteúdo da documentação. Uma instalação bem-sucedida termina sem erros.

Variáveis de ambiente

Copie o template e edite o novo arquivo:

cp .env.example .env

Você também pode usar .env.local — o Next.js carrega os dois. Nunca faça commit de segredos reais; .env* está no gitignore, exceto .env.example.

Necessárias para um boot mínimo

Essas três variáveis bastam para iniciar o servidor de desenvolvimento e rodar 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

Gere um segredo:

openssl rand -base64 32

Cole a saída em BETTER_AUTH_SECRET no .env.

Fortemente recomendadas para testar o cadastro

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.

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

Integrações opcionais

Polar, R2, PostHog, Sentry, OpenAI, Google OAuth e GitHub OAuth são todos opcionais. O app falha de forma suave quando não estão definidos — rotas não relacionadas continuam funcionando, e as páginas de feature mostram uma mensagem clara de configuração.

Veja .env.example para cada variável e comentários inline. Nunca coloque segredos de servidor em NEXT_PUBLIC_*.

Banco de dados

O Motoko Base usa PostgreSQL com Drizzle ORM. Você precisa de uma instância Postgres em execução antes de pnpm db:migrate.

Criar um banco de dados

Escolha uma opção:

  • Supabase — crie um projeto e copie a connection string em Project Settings → Database
  • Postgres local — crie um banco e um usuário, depois monte uma URL postgresql://

Para o app Next.js em runtime, prefira o transaction pooler do Supabase (muitas vezes a porta 6543). Para migrations, se o DDL falhar pelo pooler, aponte temporariamente DATABASE_URL para a conexão direta (muitas vezes a porta 5432).

Defina a URL no .env:

DATABASE_URL=postgresql://...

Rodar migrations

A partir da raiz do projeto:

pnpm db:migrate

Isso aplica as migrations SQL de drizzle/migrations/ com o Drizzle Kit. Você só precisa rodar de novo depois de puxar migrations novas ou alterar o schema você mesmo (pnpm db:generate e depois pnpm db:migrate).

Opcional: abra o Drizzle Studio para inspecionar tabelas:

pnpm db:studio

Better Auth

A autenticação é feita pelo Better Auth com um adapter Drizzle. Nenhum serviço de auth extra é necessário além do Postgres e das variáveis acima.

Para desenvolvimento local, defina:

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

Mantenha BETTER_AUTH_URL alinhado com a URL que você realmente abre no navegador — as URIs de redirecionamento OAuth e os cookies de sessão dependem dela.

Google / GitHub sign-in são opcionais. Deixe GOOGLE_* e GITHUB_* indefinidos para iniciar sem eles; os botões permanecem desabilitados até a configuração. As callback URLs devem corresponder a BETTER_AUTH_URL:

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

As rotas da API de auth ficam em /api/auth/*. As rotas protegidas do dashboard exigem uma sessão verificada.

Primeira execução

  1. Inicie o servidor de desenvolvimento:

    pnpm dev

  2. Abra http://localhost:3000.

  3. Clique em Sign up, crie uma conta com e-mail e senha.

  4. Verifique sua caixa de entrada pelo e-mail de verificação (requer Resend). Clique no link.

  5. Entre e abra o Dashboard (/dashboard).

  6. Explore as páginas principais (Settings, Billing) e as demos em Demos (Link Manager, Storage, AI Email). Demos que precisam de variáveis extras mostram um aviso de configuração em vez de quebrar.

Com apenas as variáveis mínimas, auth e o shell do dashboard funcionam. Billing permanece em Free, Storage e AI Email mostram dicas de setup, e analytics/monitoring ficam quietos.