guias
Frameworks

Deploy Next.js

Como fazer deploy de um app Next.js na Veloz em 2 minutos.

Este guia mostra como fazer deploy de uma aplicação Next.js na Veloz — do zero à produção.

Pré-requisitos

  • Node.js 18+ instalado
  • Um projeto Next.js (ou vamos criar um)
  • Conta na Veloz

1. Criar um projeto Next.js

Se você já tem um projeto, pule para o passo 2.

npx create-next-app@latest meu-app
cd meu-app

Escolha as opções que preferir (TypeScript, Tailwind, App Router, etc.).

2. Instalar a CLI da Veloz

npm install -g onveloz

3. Autenticar

veloz login

Um link abre no navegador para confirmar a autenticação.

4. Fazer deploy

veloz deploy

A CLI detecta Next.js automaticamente e configura tudo:

ℹ Framework detectado: Next.js
ℹ Build: npm run build
ℹ Start: npm start
ℹ Porta: 3000

── meu-app ──
  Nome:          meu-app
  Tipo:          Serviço Web
  Branch:        main
  Framework:     Next.js
  Build:         npm run build
  Start:         npm start
  Porta:         3000

? Confirmar e fazer deploy? (Y/n)

Confirme e aguarde. Em ~1 minuto seu app estará no ar:

✓ Build concluído em 28s
✓ Deploy concluído!
✓ https://meu-app.onveloz.com

5. Adicionar domínio (opcional)

veloz domains add meuapp.com.br

Siga as instruções para configurar o DNS. O SSL é provisionado automaticamente.

Variáveis de ambiente

Build time (NEXTPUBLIC*)

Variáveis que começam com NEXT_PUBLIC_ são injetadas no build e acessíveis no client:

veloz env set NEXT_PUBLIC_API_URL=https://api.meuapp.com

Importante: Após alterar variáveis NEXT_PUBLIC_*, faça um novo deploy para que o build inclua os novos valores.

Server-side

Variáveis sem o prefixo NEXT_PUBLIC_ ficam disponíveis apenas no servidor (API routes, Server Components, getServerSideProps):

veloz env set DATABASE_URL=postgres://user:pass@host:5432/db
veloz env set SECRET_KEY=minha-chave-secreta

App Router vs Pages Router

A Veloz suporta ambos. A detecção é automática — não precisa configurar nada diferente.

App Router (recomendado)

app/
├── layout.tsx
├── page.tsx
└── api/
    └── hello/
        └── route.ts

Pages Router

pages/
├── index.tsx
├── _app.tsx
└── api/
    └── hello.ts

Server Actions

Server Actions funcionam normalmente. A Veloz roda seu Next.js como servidor completo — não é serverless.

// app/actions.ts
"use server";
 
export async function createUser(formData: FormData) {
  const name = formData.get("name");
  // Salvar no banco...
}

API Routes

API Routes (tanto App Router quanto Pages Router) funcionam sem configuração extra:

// app/api/users/route.ts
import { NextResponse } from "next/server";
 
export async function GET() {
  return NextResponse.json({ users: [] });
}

Static Export

Se seu app é totalmente estático, configure o next.config.js:

// next.config.js
module.exports = {
  output: "export",
};

A Veloz detecta o output export e trata como site estático automaticamente.

Configuração avançada

Node.js version

{
  "services": {
    ".": {
      "build": {
        "nodeVersion": "22"
      }
    }
  }
}

Memória e CPU

Para apps Next.js maiores:

veloz config set --memory 1Gi --cpu 1

Múltiplas instâncias

veloz config set --instances 3

Troubleshooting

"Module not found" no build

Verifique se todas as dependências estão em dependencies (não só devDependencies) no package.json.

App lento no primeiro request

O primeiro request após o deploy pode ser mais lento (compilação de páginas). Isso é normal no Next.js com SSR/ISR.

Variáveis NEXTPUBLIC* não aparecem no client

Faça um novo deploy após definir as variáveis. Variáveis NEXT_PUBLIC_* são injetadas no build, não em runtime.

Próximos passos