Instalação

Pré-requisitos

• Bun 1.3+
• Node 22+ (apenas para ferramentas que ainda não suportam Bun)
• PostgreSQL 15+ (local ou Docker)
• Git

Clone & install

git clone <your-repo> my-saas
cd my-saas
bun install

Variáveis de ambiente

cp apps/server/.env.example apps/server/.env

Edite apps/server/.env:

• DATABASE_URL — connection string do Postgres
• BETTER_AUTH_SECRET — gere um com openssl rand -base64 32
• BETTER_AUTH_URL — http://localhost:3005 em dev

Database

cd apps/server
bunx prisma migrate dev   # o cliente Prisma já é gerado no `bun install` (postinstall)

Run

# a partir da raiz
bun run dev

• Client: http://localhost:3004
• Server: http://localhost:3005
• Docs: http://localhost:3004/docs

Serviços de desenvolvimento (Docker)

O stack de desenvolvimento inclui Postgres, Redis e MailHog (armadilha SMTP para testes E2E):

docker compose -f docker-compose.dev.yml up -d

MailHog captura todos os emails enviados. Web UI: http://localhost:8025. Para rotear o servidor por ele, defina SMTP_HOST=localhost e SMTP_PORT=1025 em apps/server/.env.

Testes E2E (Playwright)

A suite E2E vive em tests/ (@app/e2e). Roda sobre Node (não Bun) e maneja o stack real. Com Postgres + Redis levantados (docker compose -f docker-compose.dev.yml up -d postgres redis):

bun run e2e          # roda a suite completa contra seu dev stack já rodando
bun run e2e:golden   # apenas os golden paths (bootstrap, registro, onboarding, billing, dashboard)
bun run e2e:install  # instala o browser Chromium do Playwright (uma vez)

bun run e2e:golden é o que gateia CI em cada PR (job e2e-golden de .github/workflows/ci.yml): sobe server + client por conta própria e isola um schema Postgres por execução. A suite completa roda de noite (.github/workflows/e2e-nightly.yml) contra o stack completo do compose, que além disso inclui o worker BullMQ e MailHog.

Para espelhar o gate localmente antes de pushar:

bash scripts/ci-local.sh --e2e   # lint + typecheck + test + api-freshness + golden E2E

Troubleshooting

@prisma/client did not initialize — execute bunx prisma generate a partir de apps/server/.

O servidor quebra com Invalid environment — o .env não existe ou está faltando vars obrigatórias.