sevalla-hosting/skills

Implantando Next.js na Sevalla

Sevalla é uma PaaS (da Kinsta) com dois produtos de hospedagem para Next.js:

• Application Hosting executa um servidor Node.js real. Necessário para SSR, manipuladores de rota (rotas de API), proxy (antigamente middleware), ISR (revalidate), ações de servidor ou websockets.
• Static Site Hosting serve a saída de uma exportação estática (output: 'export'). Nenhum código do lado do servidor. Limite de 100 sites estáticos por empresa.

Acertar essa decisão é fundamental. Ela determina tudo abaixo.

Etapa 0: Decidir qual produto de hospedagem usar

Inspecione o repositório antes de fazer qualquer outra coisa:

1. Leia next.config.js / next.config.ts / next.config.mjs em busca de output: 'export' ou output: 'standalone'.
2. Pesquise no código por: app/api/, pages/api/, proxy.ts ou proxy.js (Next.js 16), middleware.ts ou middleware.js (Next.js 15 e anteriores), "use server", getServerSideProps, revalidate (ISR), NextResponse, ou qualquer cliente de banco de dados ou autenticação usado no lado do servidor.
3. Decida:
   • Qualquer um dos itens acima presente: Application Hosting (servidor necessário). Vá para a Etapa 1.
   • Nenhum presente, conteúdo puramente estático, marketing ou blog: Static Site Hosting é mais simples e barato. Leia references/static-hosting.md.
   • Não tem certeza, ou o usuário quer recursos dinâmicos depois: opte por Application Hosting. Ele pode fazer tudo que a hospedagem estática faz.

Se for realmente ambíguo, faça uma pergunta ao usuário: "Esta aplicação precisa de um servidor ativo (rotas de API, ISR, autenticação, chamadas a banco de dados) ou é totalmente estática?" Não tente adivinhar em silêncio, pois a escolha errada significa refazer toda a implantação.

Verifique também se o repositório possui um cliente de banco de dados (Prisma, Drizzle, pg, mysql2, Mongoose, redis, ioredis) e se há upload de arquivos. Se encontrar, leia references/data-services.md antes da Etapa 3.

Etapa 1: Escolher uma estratégia de build (Application Hosting)

A Sevalla constrói aplicações baseadas em Git com uma de quatro estratégias:

• Nixpacks, a padrão. Zero configuração para uma aplicação Next.js padrão. Use a menos que haja um motivo para não fazê-lo.
• Railpack, o sucessor do Nixpacks. Também zero configuração. Uma boa escolha para uma nova aplicação. Defina com o campo da API build_type: "railpack".
• Dockerfile, quando o usuário quer uma imagem pequena e reproduzível, tem um monorepo com o qual os builders de detecção automática têm dificuldade, ou pede Docker.
• Buildpacks (pack). Raramente necessário para Next.js.

Leia references/app-hosting.md antes de escrever qualquer configuração. Ele contém os scripts exatos do package.json, o Dockerfile recomendado, as substituições do nixpacks.toml e a configuração do Build path para monorepos. Não crie um Dockerfile ou nixpacks.toml do zero com base no conhecimento geral de Next.js. A Sevalla tem restrições específicas (abaixo) que guias genéricos não mencionam.

Etapa 2: Preparar o repositório (restrições da Sevalla)

Estas pegam quase toda primeira implantação. Verifique todas antes de implantar:

1. Leia a porta de $PORT e vincule a 0.0.0.0. A porta padrão do processo web é 8080, e a Sevalla a passa em PORT. Apenas as portas 80 e 443 estão abertas para a internet, e a Sevalla as roteia para $PORT. Com Nixpacks ou Railpack, o script de inicialização deve ser next start -p ${PORT:-8080} -H 0.0.0.0. Um simples next start escuta na porta 3000.
2. Variáveis NEXT_PUBLIC_* são incorporadas em tempo de build. Crie-as como variáveis em tempo de build (is_buildtime: true) antes da execução do build. Uma variável adicionada depois precisa de uma nova implantação, não de uma reinicialização.
3. O sistema de arquivos é efêmero. Qualquer coisa que a aplicação escrever em disco em tempo de execução (uploads, arquivos gerados, caches em disco) é perdida a cada nova implantação ou reinicialização. Use armazenamento de objetos ou um disco persistente se a aplicação realmente precisar de gravação em disco local (por exemplo, SQLite ou um CMS auto-hospedado). Consulte references/data-services.md.
4. output: 'standalone' apenas com o Dockerfile. next start não usa o bundle standalone, e o Next.js avisa que "next start" does not work with "output: standalone" configuration. Portanto, com Nixpacks ou Railpack, deixe output não definido. Com o Dockerfile, defina output: 'standalone'.
5. Não commite node_modules ou .next. Uma pasta node_modules commitada é uma causa documentada de falhas de build na Sevalla.
6. Fixar a versão do Node.js. Nixpacks usa Node 18 por padrão, e Next.js 16 precisa de Node 20.9 ou superior. Defina "engines": { "node": "22.x" } no package.json, ou a variável de build NIXPACKS_NODE_VERSION=22.
7. Monorepos: defina o Build path (campo da API build_path) para a pasta da aplicação Next.js, por exemplo apps/web. Com o Dockerfile, defina também docker_context e dockerfile_path.
8. Nome do package.json: não use "node" ou "js" como nome do pacote. Está documentado que quebra os builds da Sevalla.
9. Aspas duplas em valores de variáveis devem ser escapadas como \". Aspas não escapadas são removidas ou fazem a implantação falhar.
10. Segredos (URLs de banco de dados, chaves de API) vão nas variáveis de ambiente da Sevalla. Nunca commite um arquivo .env com segredos reais.

Etapa 3: Implantar

Use a primeira opção disponível, nesta ordem:

1. O servidor MCP Sevalla (https://mcp.sevalla.com/mcp). Ele tem duas ferramentas: search encontra endpoints de API na especificação, e execute executa JavaScript que chama sevalla.request({ method, path, body }). Use os caminhos de API na tabela abaixo.
2. A CLI sevalla, com --json em todo comando para que você possa ler os IDs. Instale com npm install -g @sevalla/cli (Node 22+) ou brew install sevalla-hosting/tap/sevalla. Faça login com sevalla login (autorização de dispositivo no navegador) ou defina SEVALLA_API_TOKEN.
3. A API REST em https://api.sevalla.com/v3 com uma chave de API bearer.

Se nenhuma estiver disponível, diga ao usuário como adicionar o servidor MCP (veja os guias rápidos de agentes de código em https://docs.sevalla.com/quick-starts/coding-agents/overview), ou forneça a eles os passos do dashboard em references/dashboard.md. Apenas o primeiro login precisa do usuário.

Application Hosting

#	Ação	API (MCP execute ou REST)	CLI
1	Escolher uma localização	GET /resources/clusters	sevalla resources clusters --json
2	Criar a aplicação	POST /applications com display_name, cluster_id, source (privateGit para um repositório conectado do GitHub, GitLab ou Bitbucket, publicGit para uma URL pública), git_type, repo_url, default_branch	sevalla apps create --name <nome> --cluster <id-do-cluster> --source privateGit --git-type github --repository https://github.com/<dono>/<repo> --branch <branch> --json
3	Definir a estratégia de build e o build path, se não forem os padrões	PATCH /applications/{id} com build_type (nixpacks, railpack, dockerfile, pack) e build_path	sevalla apps update <id-da-app> --build-type railpack --json. A CLI não tem flag de build path: sevalla apps update <id-da-app> --data '{"build_path":"apps/web"}' --json
4	Adicionar variáveis de ambiente	POST /applications/{id}/env-vars com key e value. is_runtime e is_buildtime ambos padrão true, o que é correto para NEXT_PUBLIC_*.	sevalla apps env-vars create <id-da-app> --key <CHAVE> --value "<valor>" (disponível em tempo de build e de execução)
5	Conectar um banco de dados, se houver	Consulte references/data-services.md
6	Implantar	POST /applications/{id}/deployments. Criar uma aplicação não inicia uma implantação.	sevalla apps deployments trigger <id-da-app> --branch <branch> --json

Se o passo 2 falhar com HTTP 500 para um repositório privateGit, a causa mais provável é que o aplicativo do GitHub da Sevalla não consegue ver o repositório. A API não informa isso. Verifique com sevalla git providers --json: o settings_url abre a instalação do aplicativo do GitHub. O usuário (ou um proprietário da organização do GitHub) deve dar ao aplicativo acesso ao repositório. Um repositório em uma organização que o usuário não possui precisa de um proprietário para adicioná-lo. Depois, tente o passo 2 novamente.

Uma nova aplicação tem implantação automática desligada. Se o usuário quiser uma implantação a cada push, defina auto_deploy: true com PATCH /applications/{id} (funciona apenas para privateGit).

Para Static Site Hosting, siga references/static-hosting.md. Criar um site estático inicia sua primeira implantação automaticamente.

Etapa 4: Verificar

Uma implantação que começou não é uma implantação que funciona. Faça todas estas verificações antes de dizer ao usuário que está pronto:

1. Aguarde o build. Consulte GET /applications/{id}/deployments/{deployment_id} (CLI: sevalla apps deployments get <id-da-implantacao> --app-id <id-da-app> --json) a cada 15 a 30 segundos até que status seja success ou failed. Outros valores são waiting, inProgress, cancelled e skipped.
2. Se falhou, leia o log do build. GET /applications/{id}/deployments/{deployment_id}/logs (CLI: sevalla apps deployments logs ...). Compare o erro com a tabela de solução de problemas em references/app-hosting.md, corrija a causa e implante novamente. Não tente adivinhar duas vezes sem ler o log. Julgue o sucesso pelo status da implantação, não pela severidade do log: a saída normal do build escrita em stderr aparece com "severity": "error" em um build bem-sucedido.
3. Encontre a URL ativa. GET /applications/{id}/domains (CLI: sevalla apps domains list --app-id <id-da-app> --json). Toda aplicação recebe um domínio *.sevalla.app gratuito após sua primeira implantação bem-sucedida.
4. Faça uma requisição para a URL. Espere HTTP 200 em / e em um manipulador de rota, se a aplicação tiver um. Um 502 ou timeout geralmente significa que o servidor não está escutando em $PORT e 0.0.0.0.
5. Se a aplicação responder com um erro, leia o log de tempo de execução. GET /applications/{id}/runtime-logs (CLI: sevalla apps logs runtime <id-da-app>).

Depois, informe ao usuário a URL ativa, o que você configurou e qualquer coisa que eles precisam fazer por conta própria (por exemplo, adicionar registros DNS para um domínio personalizado).

Etapa 5: Próximos passos opcionais

• Domínio personalizado: sevalla apps domains add <id-da-app> --name exemplo.com. O usuário deve adicionar os registros DNS que a Sevalla retorna. SSL está incluído.
• Escalonamento: sevalla apps processes update <id-do-processo> --app-id <id-da-app> --instances <n>. Com mais de uma instância, não use um disco persistente para estado compartilhado. Use armazenamento de objetos ou um banco de dados.
• Reverter: sevalla apps deployments rollback <id-da-app> --deployment-id <id-da-implantacao>.

Arquivos de referência

• references/app-hosting.md: scripts do package.json, notas sobre Nixpacks e Railpack, o Dockerfile recomendado, configuração de monorepo, tabela de solução de problemas.
• references/static-hosting.md: configuração e implantação de exportação estática para Static Site Hosting.
• references/data-services.md: bancos de dados, armazenamento de objetos e discos persistentes, e como seus detalhes de conexão chegam à aplicação.
• references/dashboard.md: os mesmos passos no dashboard da Sevalla, para uma pessoa.