Instalación de Node.js y npm para compilación de assets

Node.js y npm están disponibles en todos los servicios de hosting para asistir en el proceso de compilación de assets y ejecución de comandos durante los despliegues. Esta herramienta está pensada para compilar CSS/JavaScript y ejecutar comandos de build, no para ejecutar aplicaciones Node.js como servidor.

Accede al área de clientes, sección Hosting, selecciona el servicio de hosting donde quieres instalar Node.js y accede a la sección Gestor de paquetes.

Instalación de Node.js

Si no tienes Node.js instalado, verás una tarjeta con el estado No instalado y un interruptor apagado. Enciéndelo y se abrirá el panel de Node.js con las versiones disponibles en ese momento.

El propio panel te dice con cuál quedarte si no tienes preferencia; sigue esa recomendación salvo que la propiedad engines.node de tu package.json exija otra. Antes de decidir, comprueba también el ciclo de vida oficial de Node.js: las etiquetas LTS y las fechas de fin de soporte cambian con el tiempo, por lo que esta guía no fija números de versión.

Las versiones EOL no deben usarse en nuevos proyectos ni despliegues normales. Si el panel conserva alguna para facilitar una migración, úsala solo de forma temporal, aislada y sin servicios persistentes, con una fecha definida para actualizar dependencias y retirar ese entorno.

Selecciona la versión y haz clic en Instalar NVM y Node.js con el número de versión. El proceso instala NVM (Node Version Manager), descarga e instala Node.js, configura npm automáticamente, añade la configuración a tu .bashrc y verifica la instalación. Una vez completado verás un mensaje de éxito con las versiones instaladas.

Cambio de versión

En la tarjeta Node.js del Gestor de paquetes pulsa Cambiar versión, selecciona la nueva y haz clic en Cambiar a vX.x. El sistema descargará la nueva versión si no está instalada, la configurará como predeterminada y verificará que funciona correctamente.

Cambiar la versión afecta a todos los proyectos en el mismo servicio de hosting. Si necesitas versiones diferentes para proyectos distintos, usa nvm use manualmente en tus scripts.

Ejemplos de uso

La instalación de Node.js añade automáticamente la configuración necesaria a tu .bashrc, lo que hace que Node.js esté disponible en sesiones SSH interactivas y en el ejecutor de comandos del panel. Sin embargo, en los scripts de deploy personalizados y cronjobs es necesario activar NVM manualmente porque estos contextos no cargan .bashrc automáticamente.

Los ejemplos de compilación presuponen que package.json y package-lock.json están en el repositorio y sincronizados. Instala o actualiza dependencias en desarrollo, prueba el resultado y guarda ambos archivos. npm ci reconstruye node_modules según el bloqueo; --include=dev incluye las herramientas de build aunque el entorno sea de producción.

Desde scripts de deploy

El caso de uso principal es combinarlo con la herramienta de deploy automático desde GitHub. El editor ejecuta un comando por línea y cada línea abre su propia shell: activa NVM en la misma línea que use npm o npx, no en una línea aparte.

Laravel con 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

Proyecto con Tailwind CSS y su CLI ya declarados como dependencias:

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 con 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

Desde SSH y ejecutor de comandos

Cuando te conectas por SSH de forma interactiva o usas el ejecutor de comandos del panel de deploy, Node.js está disponible automáticamente sin necesidad de exportar nada. Simplemente conecta vía SSH o usa el ejecutor de comandos y ejecuta directamente:

Compilar assets manualmente:

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

Compilar Tailwind CSS con sus dependencias ya declaradas:

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

Optimizar imágenes con sharp, si el proyecto incluye esa dependencia y el script indicado:

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

Ejecutar tests:

npm ci --include=dev
npm test

Compilar TypeScript, si está declarado y configurado en el proyecto:

npm ci --include=dev
npx tsc

Desinstalación

Apaga el interruptor de la tarjeta Node.js y confirma en Desinstalar Node.js. Esto elimina todas las versiones de Node.js, NVM, paquetes npm globales guardados en NVM y las líneas de configuración de NVM en .bashrc. Los node_modules locales de tus proyectos no se eliminan con esta acción. Antes de desinstalar, revisa los deploys y cronjobs que dependan de Node.

Limitaciones importantes

Esta herramienta está pensada para asistir en el deploy compilando assets y ejecutando comandos, no para ejecutar aplicaciones Node.js como servidor. Casos válidos incluyen compilar CSS/JavaScript con PostCSS, Sass, Tailwind, Webpack, Vite o Rollup, optimizar imágenes, ejecutar tests y generar documentación. También puedes alojar React, Vue u otra web estática conectada a una API externa: una vez compilada, el hosting solo sirve sus ficheros y el navegador o un backend PHP pueden comunicarse con la API por HTTPS.

No es adecuada para servidores Express, Next.js en modo servidor, WebSocket o APIs REST que necesiten ejecutarse constantemente. Para esos casos necesitas un entorno que admita procesos Node persistentes y gestione su publicación HTTP, reinicio y puertos. Instalar Node desde esta tarjeta no configura ese servicio; confirma la compatibilidad de tu proyecto antes de contratar otro entorno.

Los comandos npm están sujetos a los límites de CPU y RAM del plan de hosting, y a los tiempos máximos del ejecutor que utilices. Si tus compilaciones requieren muchos recursos, considera compilar en local o en un sistema CI/CD y subir solo los assets compilados. Algunos paquetes npm que requieren compilación de código nativo pueden fallar si necesitan dependencias del sistema no disponibles.

Solución de problemas

"NVM no encontrado" o "npm command not found" en scripts de deploy: Incluye la carga de NVM en la misma línea que use npm o npx, como muestran los ejemplos de despliegue. Si tampoco aparece en una sesión interactiva, comprueba que se haya cargado NVM.

"npm command not found" en SSH interactivo: Verifica que Node.js esté instalado correctamente en el Gestor de paquetes. Si está instalado pero no funciona, cierra y vuelve a abrir tu sesión SSH para que se cargue .bashrc, o ejecuta source ~/.bashrc.

Instalación de paquetes muy lenta: La primera vez que ejecutas npm install puede tardar varios minutos porque npm descarga todas las dependencias. La caché puede reducir descargas posteriores, aunque la compilación y los scripts de instalación siguen consumiendo recursos.

Error "EACCES: permission denied" al instalar un paquete global: Suele indicar que NVM no está activo en esa shell y npm intenta escribir fuera de tu cuenta. Activa NVM con . "$HOME/.nvm/nvm.sh" y repite; con NVM los paquetes globales se instalan dentro de $HOME/.nvm.

La versión de Node.js no coincide: Si node --version muestra una versión diferente, asegúrate de haber cambiado la versión predeterminada desde el Gestor de paquetes o usa nvm use VERSION para cambiar temporalmente.

Integración con otras herramientas

Puedes usar Node.js con el sistema de deploy automático desde GitHub para compilar assets automáticamente en cada despliegue sin subirlos al repositorio. Puedes combinar Composer y npm en el mismo script de deploy:

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

También puedes usar Node.js en cronjobs para tareas programadas. Al igual que en los scripts de deploy, necesitas activar NVM manualmente porque los cronjobs no cargan .bashrc:

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

Antes de automatizar, ejecuta una compilación de prueba y comprueba que se genera el directorio esperado y que la web carga sus recursos.