guias
Projetos

Full-Stack App

Como fazer deploy de um app full-stack (frontend + API + banco) na Veloz.

Este guia mostra como fazer deploy de uma aplicação completa — frontend, API e banco de dados — na Veloz.

Arquitetura

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│              │      │              │      │              │
│   Frontend   │─────▶│     API      │─────▶│   Database   │
│              │      │              │      │              │
│  Next.js     │      │  Hono        │      │  PostgreSQL  │
│  Vite+React  │      │  Express     │      │  Neon        │
│              │      │              │      │  Supabase    │
└──────────────┘      └──────────────┘      └──────────────┘
   meuapp.com          api.meuapp.com          (managed)

Opção 1: Next.js full-stack (mais simples)

Se seu projeto usa Next.js com API Routes ou Server Actions, você só precisa de um serviço:

veloz deploy

Tudo roda junto — frontend, API e Server Actions no mesmo deploy.

Banco de dados

Use um PostgreSQL gerenciado:

  • Neon — serverless Postgres, free tier generoso
  • Supabase — Postgres + Auth + Storage
  • PlanetScale — MySQL serverless
veloz env set DATABASE_URL=postgres://user:pass@host:5432/db

Exemplo com Prisma

npm install prisma @prisma/client
npx prisma init
// app/api/users/route.ts
import { PrismaClient } from "@prisma/client";
 
const prisma = new PrismaClient();
 
export async function GET() {
  const users = await prisma.user.findMany();
  return Response.json(users);
}
 
export async function POST(req: Request) {
  const data = await req.json();
  const user = await prisma.user.create({ data });
  return Response.json(user, { status: 201 });
}

Opção 2: Monorepo (frontend + API separados)

Para projetos maiores, separe frontend e API:

meu-projeto/
├── package.json
├── veloz.json
├── apps/
│   ├── web/              ← Next.js ou Vite
│   │   ├── package.json
│   │   └── src/
│   └── api/              ← Hono ou Express
│       ├── package.json
│       └── src/
└── packages/
    ├── db/               ← Prisma schema + client
    └── shared/           ← Types compartilhados

Setup do monorepo

// package.json (raiz)
{
  "workspaces": ["apps/*", "packages/*"]
}

Deploy

veloz deploy
ℹ Monorepo detectado (npm)

? Quais apps deseja fazer o deploy?
  ✔ web (Next.js) — apps/web
  ✔ api (Hono) — apps/api

? Confirmar e fazer deploy? (Y/n)

Ambos são deployados em paralelo. Cada um recebe sua URL:

✓ web → meu-projeto-web.onveloz.com
✓ api → meu-projeto-api.onveloz.com

Conectando frontend → API

No frontend, aponte para a URL da API:

veloz env set NEXT_PUBLIC_API_URL=https://meu-projeto-api.onveloz.com
# ou
veloz env set VITE_API_URL=https://meu-projeto-api.onveloz.com

Domínios customizados

veloz domains add meuapp.com --service web
veloz domains add api.meuapp.com --service api

Autenticação

Better Auth

npm install better-auth
// packages/auth/index.ts
import { betterAuth } from "better-auth";
 
export const auth = betterAuth({
  database: process.env.DATABASE_URL,
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID,
      clientSecret: process.env.GITHUB_CLIENT_SECRET,
    },
  },
});
veloz env set GITHUB_CLIENT_ID=...
veloz env set GITHUB_CLIENT_SECRET=...

NextAuth.js

veloz env set NEXTAUTH_SECRET=meu-segredo-aleatorio
veloz env set NEXTAUTH_URL=https://meuapp.com

Cache (Redis)

Para apps que precisam de cache:

npm install ioredis
veloz env set REDIS_URL=redis://...
import Redis from "ioredis";
 
const redis = new Redis(process.env.REDIS_URL);
 
app.get("/users", async (c) => {
  const cached = await redis.get("users");
  if (cached) return c.json(JSON.parse(cached));
 
  const users = await prisma.user.findMany();
  await redis.set("users", JSON.stringify(users), "EX", 60);
  return c.json(users);
});

Checklist de produção

  • Variáveis de ambiente configuradas
  • Banco de dados conectado e migrado (npx prisma migrate deploy)
  • CORS configurado na API (apenas domínios permitidos)
  • Health check respondendo
  • Domínios configurados com SSL
  • Logs funcionando (veloz logs)
  • Monitoramento de erros (Sentry, etc.)

Próximos passos