Como instalar Angular no Saplo (SPA empresarial)

O Angular é o mais completo dos frameworks de frontend populares - impõe a sua própria estrutura de projeto, tipagem através do TypeScript e módulos, o que funciona bem em grandes aplicações corporativas mantidas por uma equipa inteira. Assim como o React ou o Vue, o Angular não é um hosting por si só - um projeto construído são ficheiros estáticos HTML, CSS e JS que requerem um servidor com um fallback de rotas correto para o Angular Router no modo de histórico. No Saplo, implementas o Angular da mesma forma que qualquer outra aplicação do catálogo: o motor cria o projeto, constrói-o através do Angular CLI, deteta o diretório real com o index.html resultante e expõe-no sob o nginx juntamente com o fallback de rotas.

Para quem é o Angular na Saplo

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

• estás a construir um grande sistema interno ou um painel para várias funções - a estrutura de módulos e a tipagem rigorosa do Angular facilitam a manutenção do código quando várias pessoas trabalham no projeto,
• a equipa já conhece o Angular - a Saplo não impõe nenhuma camada adicional, recebes um projeto padrão gerado pelo Angular CLI,
• o frontend deve ligar-se à sua própria API - implementas um SPA ao lado do backend (Django, Node, Docker) no mesmo Box ou separadamente,
• aplicação de página única com Angular Router em modo de histórico - o fallback de todas as rotas para index.html é configurado automaticamente, não precisas de adicionar nada no nginx,
• queres implementações com git push em vez de carregamento manual de ficheiros via FTP - ligas o repositório uma vez, cada push para o branch de produção constrói e implementa automaticamente uma nova versão.

Se o projeto for menor e não precisares da estrutura completa de módulos do Angular, verifica no catálogo de aplicações stacks mais leves como React ou Vue.

Requisitos

Para instalares Angular na Saplo, precisas de:

• Uma Box pelo menos no plano S - uma SPA (Single Page Application) construída é um punhado de ficheiros estáticos, mas o processo de compilação do Angular CLI é mais pesado do que no React ou Vue, por isso o manifesto da receita requer um mínimo de 512 MB de RAM livre para a compilação e 3 GB de espaço em disco.
• Um domínio ou subdomínio *.saploapp.pl incluído em todos os planos.
• Um repositório Git, se quiseres implementações automáticas (opcional no início, também podes carregar a aplicação como um arquivo .zip através do Painel).

Instalação passo a passo

1. No Painel Saplo, acede ao Catálogo de aplicações e seleciona Angular (categoria "Aplicações").
2. Indica a Box e o nome da aplicação - a partir dele será criado o subdomínio padrão <name>.saploapp.pl.
3. Escolhe a versão Node.js para a construção (18, 20 ou 22, por padrão 20) e confirma a instalação.
4. O motor cria a estrutura do Angular através do Angular CLI (equivalente a ng new --defaults --ssr=false), instala as dependências e constrói o projeto para produção (ng build --configuration=production).
5. Após a construção, o motor deteta automaticamente se o ficheiro resultante index.html se encontra em dist/<project>/ (Angular anterior à versão 17) ou em dist/<project>/browser/ (Angular 17 e mais recente, onde o diretório dist está preparado para SSR), e copia o nível de diretório correto para a aplicação servida pelo nginx.
6. Após a conclusão da instalação, o domínio do passo 2 mostra a estrutura inicial do Angular - a partir deste momento, podes implementar o teu próprio código nele.

Implementar o teu próprio código via 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" e indica o repositório com o projeto Angular.
2. Na diretoria raiz do repositório, o ficheiro saplo.yaml tem de estar presente.
3. Faz commit e push do ficheiro saplo.yaml para o ramo de produção (por predefinição main).
4. Cada git push subsequente para este ramo cria o projeto e substitui os ficheiros resultantes na Box, o estado é visível no separador Implementações.
5. Se a compilação falhar, a versão anterior em funcionamento permanece no lugar - o Saplo não a substitui por uma versão corrompida.

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

name: my-project
stack: angular
build:
  install: npm ci
  command: npm run build
  output: dist/my-project/browser

Se não definires o campo build.output, o motor irá, ainda assim, detetar a diretoria correta com index.html por si próprio, mas a definição explícita acelera a compilação e elimina erros em projetos com um nome personalizado.

Angular na Saplo vs alternativas

Perguntas frequentes

O Angular Router no modo de histórico funciona sem configuração adicional? Sim, o fallback de todos os caminhos para index.html está ativo imediatamente após a instalação, para que a atualização de qualquer subpágina não resulte num erro 404.

O Angular 17 alterou a estrutura do diretório dist - isso é um problema no Saplo? Não, após o build, o motor verifica automaticamente se index.html está em dist/<project>/ ou em dist/<project>/browser/, e copia o nível de diretório correto sem a tua intervenção.

Posso ter várias aplicações Angular numa Box? Sim, o Catálogo de aplicações permite configurar vários módulos lado a lado, cada um com o seu próprio subdomínio ou domínio.

Terei SSL e o meu próprio domínio? Sim, o certificado SSL é automático, e o domínio ou subdomínio *.saploapp.pl está incluído no preço de cada plano.

Como posso alterar o diretório de saída do build se o meu projeto tiver um nome personalizado? Define o campo build.output em saplo.yaml para o caminho correto, por exemplo dist/project-name/browser.

Com o Angular no Saplo, passas de zero a um domínio funcional em minutos, e o motor deteta automaticamente as alterações na estrutura do diretório dist entre as versões do Angular. Se o projeto for menor do que uma aplicação empresarial típica, verifica no mesmo catálogo as stacks mais leves React ou Vue.