Instalação do Node.js e do npm para compilação de assets

O Node.js e o npm estão disponíveis em todos os serviços de alojamento para apoiar o processo de compilação de assets e a execução de comandos durante as implementações. Esta ferramenta destina-se a compilar CSS/JavaScript e executar comandos de build, não a executar aplicações Node.js como servidor.

Aceda à área de cliente, secção Alojamento, selecione o serviço de alojamento onde quer instalar o Node.js e abra a secção Gestor de pacotes.

Instalação do Node.js

Se não tiver o Node.js instalado, verá um cartão com o estado Não instalado e um interruptor desligado. Ligue-o e abrir-se-á o painel do Node.js com as versões disponíveis nesse momento.

O próprio painel indica qual deve escolher se não tiver preferência; siga essa recomendação, a menos que a propriedade engines.node do seu package.json exija outra. Antes de decidir, consulte também o ciclo de vida oficial do Node.js: as etiquetas LTS e as datas de fim de suporte mudam com o tempo, pelo que este guia não fixa números de versão.

As versões EOL não devem ser utilizadas em novos projetos nem em implementações normais. Se o painel mantiver alguma para facilitar uma migração, utilize-a apenas de forma temporária, isolada e sem serviços persistentes, com uma data definida para atualizar as dependências e retirar esse ambiente.

Selecione a versão e clique em Instalar NVM e Node.js com o número da versão. O processo instala o NVM (Node Version Manager), descarrega e instala o Node.js, configura o npm automaticamente, adiciona a configuração ao seu .bashrc e verifica a instalação. Quando terminar, verá uma mensagem de sucesso com as versões instaladas.

Mudança de versão

No cartão Node.js do Gestor de pacotes, carregue em Mudar versão, selecione a nova e clique em Mudar para vX.x. O sistema descarregará a nova versão se não estiver instalada, configurá-la-á como predefinida e verificará que funciona corretamente.

Mudar a versão afeta todos os projetos do mesmo serviço de alojamento. Se precisar de versões diferentes para projetos distintos, utilize nvm use manualmente nos seus scripts.

Exemplos de utilização

A instalação do Node.js adiciona automaticamente a configuração necessária ao seu .bashrc, o que torna o Node.js disponível nas sessões SSH interativas e no executor de comandos do painel. No entanto, nos scripts de implementação personalizados e nos cronjobs é necessário ativar o NVM manualmente, porque estes contextos não carregam o .bashrc automaticamente.

Os exemplos de compilação partem do princípio de que package.json e package-lock.json estão no repositório e sincronizados. Instale ou atualize as dependências em desenvolvimento, teste o resultado e guarde ambos os ficheiros. npm ci reconstrói node_modules de acordo com o bloqueio; --include=dev inclui as ferramentas de build mesmo que o ambiente seja de produção.

A partir de scripts de implementação

O caso de utilização principal é combiná-lo com a ferramenta de implementação automática a partir do GitHub. O editor executa um comando por linha e cada linha abre a sua própria shell: ative o NVM na mesma linha que utiliza npm ou npx, não numa linha à parte.

Laravel com Vite:

export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm ci --include=dev
export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm run build

Laravel Mix:

export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm ci --include=dev
export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm run production

Projeto com o Tailwind CSS e a sua CLI já declarados como dependências:

export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm ci --include=dev
export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --minify

WordPress com tema personalizado:

export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && cd wp-content/themes/mi-tema && npm ci --include=dev
export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && cd wp-content/themes/mi-tema && npm run build

Por SSH e no executor de comandos

Quando se liga por SSH de forma interativa ou utiliza o executor de comandos do painel de implementação, o Node.js está disponível automaticamente sem necessidade de exportar nada. Basta ligar-se por SSH ou utilizar o executor de comandos e executar diretamente:

Compilar assets manualmente:

cd /home/usuario/apps/mi-proyecto &&
npm ci --include=dev &&
npm run build

Compilar o Tailwind CSS com as suas dependências já declaradas:

npm ci --include=dev
npx @tailwindcss/cli -i ./src/styles.css -o ./public/styles.css --minify

Otimizar imagens com o sharp, se o projeto incluir essa dependência e o script indicado:

npm ci --include=dev
node optimize-images.js

Executar testes:

npm ci --include=dev
npm test

Compilar TypeScript, se estiver declarado e configurado no projeto:

npm ci --include=dev
npx tsc

Desinstalação

Desligue o interruptor do cartão Node.js e confirme em Desinstalar Node.js. Isto elimina todas as versões do Node.js, o NVM, os pacotes npm globais guardados no NVM e as linhas de configuração do NVM no .bashrc. Os node_modules locais dos seus projetos não são eliminados com esta ação. Antes de desinstalar, reveja as implementações e os cronjobs que dependam do Node.

Limitações importantes

Esta ferramenta destina-se a apoiar a implementação compilando assets e executando comandos, não a executar aplicações Node.js como servidor. Os casos válidos incluem compilar CSS/JavaScript com PostCSS, Sass, Tailwind, Webpack, Vite ou Rollup, otimizar imagens, executar testes e gerar documentação. Também pode alojar React, Vue ou outro site estático ligado a uma API externa: depois de compilado, o alojamento só serve os seus ficheiros e o navegador ou um backend PHP podem comunicar com a API por HTTPS.

Não é adequada para servidores Express, Next.js em modo servidor, WebSocket ou APIs REST que precisem de estar sempre em execução. Para esses casos, precisa de um ambiente que suporte processos Node persistentes e que gira a sua publicação HTTP, o reinício e as portas. Instalar o Node a partir deste cartão não configura esse serviço; confirme a compatibilidade do seu projeto antes de contratar outro ambiente.

Os processos persistentes dos planos Avanza, Max e Elastic mantêm em execução workers de filas, o Horizon ou comandos próprios, mas destinam-se a trabalhos em segundo plano: não damos suporte a um servidor Node.js nem a outros programas que escutem numa porta. Se o que precisa são WebSockets para uma aplicação Laravel, ligue-a a um serviço compatível com Pusher, como explicamos em WebSockets no Laravel.

Os comandos npm estão sujeitos aos limites de CPU e RAM do plano de alojamento e aos tempos máximos do executor que utilizar. Se as suas compilações exigirem muitos recursos, considere compilar localmente ou num sistema de CI/CD e enviar apenas os assets compilados. Alguns pacotes npm que exigem compilação de código nativo podem falhar se precisarem de dependências do sistema não disponíveis.

Resolução de problemas

"NVM não encontrado" ou "npm command not found" em scripts de implementação: inclua o carregamento do NVM na mesma linha que utiliza npm ou npx, como mostram os exemplos de implementação. Se também não aparecer numa sessão interativa, verifique se o NVM foi carregado.

"npm command not found" em SSH interativo: verifique se o Node.js está corretamente instalado no Gestor de pacotes. Se estiver instalado mas não funcionar, feche e volte a abrir a sua sessão SSH para que o .bashrc seja carregado, ou execute source ~/.bashrc.

Instalação de pacotes muito lenta: na primeira vez que executa npm install, pode demorar vários minutos, porque o npm descarrega todas as dependências. A cache pode reduzir as transferências seguintes, embora a compilação e os scripts de instalação continuem a consumir recursos.

Erro "EACCES: permission denied" ao instalar um pacote global: costuma indicar que o NVM não está ativo nessa shell e que o npm tenta escrever fora da sua conta. Ative o NVM com . "$HOME/.nvm/nvm.sh" e repita; com o NVM, os pacotes globais são instalados dentro de $HOME/.nvm.

A versão do Node.js não coincide: se node --version mostrar uma versão diferente, certifique-se de que mudou a versão predefinida no Gestor de pacotes ou utilize nvm use VERSION para mudar temporariamente.

Integração com outras ferramentas

Pode utilizar o Node.js com o sistema de implementação automática a partir do GitHub para compilar assets automaticamente em cada implementação sem os enviar para o repositório. Pode combinar o Composer e o npm no mesmo script de implementação:

composer install --no-dev --optimize-autoloader
export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm ci --include=dev
export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && npm run build
php artisan config:cache
php artisan route:cache
php artisan view:cache

Também pode utilizar o Node.js em cronjobs para tarefas agendadas. Tal como nos scripts de implementação, tem de ativar o NVM manualmente, porque os cronjobs não carregam o .bashrc:

export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && cd /home/usuario/public_html && node scripts/tarea.js

Antes de automatizar, execute uma compilação de teste e verifique que o diretório esperado é gerado e que o site carrega os seus recursos.