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. Haz click en Gestionar Node.js para acceder al asistente de instalación donde podrás elegir entre diferentes versiones:

• Node.js 22 (Recomendada) - La versión más reciente con las últimas características
• Node.js 20 - Versión LTS (Long Term Support)
• Node.js 18 - Versión LTS anterior
• Node.js 16 - Para proyectos que requieren compatibilidad con versiones antiguas

Si no estás seguro qué versión necesitas, revisa el package.json de tu proyecto en la propiedad engines.node, o usa la versión 22 que es compatible con la mayoría de proyectos modernos. Selecciona la versión, haz click en Instalar NVM y Node.js y confirma. 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. Tarda entre 1 y 3 minutos. Una vez completado verás un mensaje de éxito con las versiones instaladas.

Cambio de versión

Desde el Gestor de paquetes → Gestionar Node.js, selecciona la nueva versión, haz click en Cambiar a vX.x y confirma. 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.

Desde scripts de deploy

El caso de uso principal es combinarlo con la herramienta de deploy automático desde GitHub. En el editor de scripts personalizados del sistema de deploy, añade export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" al inicio y luego los comandos para compilar tus assets:

Laravel con Vite:

export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh"
npm install
npm run build

Laravel Mix:

export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh"
npm install
npm run production

Proyecto con Tailwind CSS:

export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh"
npm install
npx tailwindcss -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 install
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 public_html/mi-proyecto
npm install
npm run build

Compilar Tailwind CSS:

npm install -D tailwindcss
npx tailwindcss -i ./src/styles.css -o ./public/styles.css --minify

Optimizar imágenes con sharp:

npm install sharp
node optimize-images.js

Ejecutar tests:

npm install
npm test

Compilar TypeScript:

npm install typescript
npx tsc

Desinstalación

Desde el Gestor de paquetes → Gestionar Node.js → Desinstalar NVM y Node.js. Esto elimina todas las versiones de Node.js, NVM, paquetes npm instalados y configuraciones en .bashrc.

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. No es adecuada para servidores Express, Next.js en modo servidor, WebSocket o APIs REST que necesiten ejecutarse constantemente. Para esos casos necesitas un VPS.

Los comandos npm están sujetos a los límites de CPU y RAM del plan de hosting, y no deben tardar más de 15-30 minutos. 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: Asegúrate de incluir export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" al inicio de tus scripts de deploy. No es necesario en SSH interactivo o en el ejecutor de comandos.

"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. Despliegues posteriores son más rápidos gracias a la caché.

Error "EACCES: permission denied": Si intentas instalar paquetes globales con -g, usa npm install sin -g en el directorio del proyecto.

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

La combinación ideal es 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 install
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

Con Node.js y el sistema de deploy configurados, tendrás un flujo profesional que compila automáticamente tus assets con cada push.