Después de subir una actualización, el sitio en producción comenzó a mostrar un error 500 porque Laravel no encontraba uno de los archivos CSS registrados en el manifest de Vite.

El problema ocurrió porque se agregó un nuevo archivo de estilos, pero el build de Vite que estaba en producción no había sido actualizado. Por eso, Laravel intentaba cargar un archivo que todavía no estaba registrado en el manifest.json.

Texto
Illuminate\Foundation\ViteException
Unable to locate file in Vite manifest: resources/css/pages/explore-more.css.

¿Cómo se solucionó?

Se habilitó Node.js en el hosting mediante cPanel para poder realizar la compilación directamente en el servidor.

Durante el proceso aparecieron dos problemas adicionales:

Vite no estaba disponible porque las dependencias de desarrollo no se habían instalado.

Nota: esto solo funciona cuando tienes en tu hosting Setup Node.js App

Crear una app Node en cPanel

cPanel trae una sección Setup Node.js App que permite activar una versión de Node de forma aislada, sin tocar el PHP que sirve el sitio. El truco: no hace falta que sea una app "de verdad" corriendo — solo sirve para que cPanel te preste el binario de node/npm.

Configuración usada:

  • Node.js version: 20 (la más reciente disponible)
  • Application root: nodebuild (una carpeta nueva y vacía 
  • Application URL: un subdominio que no se usa para nada (para que el formulario lo acepte, sin que afecte al sitio real)
  • Application startup file: cualquier nombre (app.js), nunca se ejecuta

Al crear la app, cPanel entrega un comando de activación tipo:

source /home/USUARIO/nodevenv/nodebuild/20/bin/activate && cd /home/USUARIO/nodebuild


Ese comando agrega node/npm al PATH solo para esa sesión de terminal. Cada vez que abres una SSH nueva hay que volver a correrlo.

Ahora solo tienes que ir a a tu terminal de tu Cpanel o atreves de SSH

cd ~/public_html
source /home/USUARIO/nodevenv/nodebuild/20/bin/activate
RAYON_NUM_THREADS=1 npm run build
php artisan config:clear
php artisan view:clear