Como instalar o Next.js no Saplo

O Next.js é a escolha por excelência hoje em dia se estás a desenvolver um site ou uma aplicação em React que precisa de carregar rapidamente e ter um bom desempenho nos resultados de pesquisa. A renderização do lado do servidor e o App Router fazem uma diferença que uma aplicação SPA clássica, composta apenas por um build estático, não consegue oferecer. O problema é que essa aplicação necessita de um processo Node.js a correr em segundo plano, não apenas de um diretório com ficheiros HTML, por isso, hospedá-la num alojamento partilhado comum não costuma resultar. No Saplo, instalas o Next.js como qualquer outra aplicação do Catálogo de aplicações, e o Saplo executa-o imediatamente como um serviço gerido com reinício automático. Abaixo, mostramos-te como fazê-lo de raiz, incluindo a ligação ao teu próprio repositório Git.

Para quem é o Next.js no Saplo

Antes de começar a instalação, verifica se é a melhor escolha para o teu projeto:

• tens ou estás a construir um projeto em Next.js com App Router - o Saplo deteta a estrutura do projeto e executa next start como um serviço, não precisas de escrever a configuração do pm2 ou systemd manualmente,
• precisas de SSR ou ISR, e não apenas de uma compilação estática - se a tua página for totalmente estática, uma stack React ou Astro do mesmo Catálogo de aplicações será mais barata e leve,
• queres implementações com git push em vez de carregamento manual de ficheiros - vinculas o repositório uma vez, e cada push para o ramo de produção constrói e implementa automaticamente uma nova versão,
• a tua fatura de alojamento está a aumentar para um projeto que está atualmente no Vercel ou Netlify - migras o código um para um, next.config.* permanece inalterado, pagas pela Box em vez do consumo de funcionalidades.

Se o teu projeto é puro frontend sem necessidade de renderização do lado do servidor, consulta a stack React ou Astro no Catálogo de aplicações; ambas são mais leves e baratas de manter.

Requisitos

Para teres o Next.js na Saplo, precisas de:

• Uma Box no plano L ou superior - a Saplo recomenda oficialmente este nível para o Next.js, porque o renderização do lado do servidor precisa de mais RAM do que uma página estática comum. Planos mais baixos são suficientes apenas para um tráfego de teste muito pequeno.
• No mínimo, 512 MB de RAM livre e 2 GB de espaço em disco para o processo da aplicação.
• Um domínio ou subdomínio *.saploapp.pl incluído no preço de cada plano, onde a aplicação será alojada.
• Um repositório Git no GitHub, GitLab ou Bitbucket, se quiseres usar a implementação automática (opcional para começar, também podes carregar a aplicação como um arquivo .zip através do painel).
• Geralmente, NÃO precisas de uma base de dados separada, a menos que a tua aplicação se conecte a uma. A Saplo não te impõe isso.

Instalação passo a passo

1. No Painel Saplo, acede ao Catálogo de aplicações e seleciona Next.js (categoria "Frameworks").
2. Indica a Box no plano L ou superior e o nome da aplicação - a partir dele é criada a subdomínio predefinida <name>.saploapp.pl, podes adicionar o teu próprio Domínio agora ou mais tarde.
3. Confirma a instalação. O motor provisiona o módulo na Box e inicia o esqueleto de arranque do Next.js (equivalente a create-next-app), para que haja algo visível sob o domínio imediatamente, antes de implementares o teu próprio código.
4. O Saplo executa a aplicação como um serviço gerido com reinício automático, e o nginx na Box direciona o tráfego do Domínio para a porta do processo Next.js.
5. Após a conclusão da instalação, o Domínio do passo 2 mostra uma página inicial funcional - a partir desse momento, implementas o teu próprio projeto nela.

Implementar o teu próprio código através do Git

1. Nos detalhes da aplicação, encontra a secção Git / CI-CD e clica em "Ligar GitHub". Confirma a instalação da aplicação "Saplo Deploy" na tua conta ou organização e indica o repositório com o projeto Next.js.
2. Na pasta raiz do repositório, deve estar o ficheiro saplo.yaml. Podes geri-lo com o comando saplo init ou escrevê-lo manualmente (exemplo abaixo).
3. Confirma e envia o ficheiro saplo.yaml para o branch de produção (por predefinição main; podes alterá-lo na secção branches.production do mesmo ficheiro).
4. Cada git push subsequente para este branch inicia uma construção e implementação automáticas. Podes ver o Estado no painel, no separador Deployments, e como um indicador verde ou vermelho ao lado do commit no GitHub.
5. Se a construção ou o healthcheck falhar, a versão anterior em funcionamento da aplicação permanece no lugar; a Saplo não a substitui por uma versão com problemas.

Exemplo de um ficheiro mínimo saplo.yaml para Next.js:

name: my-project
stack: nextjs
runtime:
  node: "22"
build:
  install: npm ci
  command: npm run build
start:
  command: npm start
  port: 3000

Enviar este ficheiro é o mesmo que qualquer outro commit:

git add saplo.yaml
git commit -m "add saplo.yaml"
git push origin main

Next.js na Saplo vs. Alternativas

Perguntas Frequentes

Preciso de configurar o Git de imediato, ou posso começar sem ele? Podes começar sem o Git. A instalação a partir do Catálogo de aplicações cria um esqueleto Next.js funcional, e a primeira implementação do teu próprio código pode ser feita através do upload de um arquivo .zip no painel. Podes configurar o Git a qualquer momento posterior.

Porque é que o Box L é recomendado, e não um plano inferior? Porque a renderização do lado do servidor (SSR) mantém o processo Node.js constantemente em memória e responde a cada pedido de novo, ao contrário de uma página estática que, uma vez construída, permanece no disco. Planos inferiores são suficientes para testes, mas sob tráfego de produção real, faltar-lhes-á RAM.

O que acontece se o ficheiro saplo.yaml não estiver no repositório? Na primeira implementação sem este ficheiro, o deploy terminará com um erro. Nas implementações subsequentes, se o ficheiro desaparecer de um commit específico, o Saplo usará a configuração da última implementação bem-sucedida.

Preciso de configurar a porta da aplicação manualmente? Não precisas, a porta predefinida é 3000 e a maioria dos projetos Next.js não exige a sua alteração. Se a tua aplicação a alterar, define-a na secção start.port do ficheiro saplo.yaml.

Posso ter várias aplicações Next.js num único Box? Sim, o Catálogo de aplicações permite instalar vários módulos num Box, cada um com a sua própria subdomínio ou domínio, desde que haja RAM e espaço em disco suficientes atribuídos ao plano.

Com o Saplo, podes configurar o Next.js do zero para um domínio funcional em minutos, e cada git push subsequente implementa uma nova versão sem a tua intervenção. Se estiveres a migrar um projeto existente do Vercel ou Netlify e algo não funcionar como deveria, escreve-nos, nós ajudaremos a escolher a configuração em saplo.yaml.