Installation de Node.js et npm pour la compilation des assets

Node.js et npm sont disponibles sur tous les services d'hébergement pour faciliter la compilation des assets et l'exécution de commandes pendant les déploiements. Cet outil est conçu pour compiler du CSS/JavaScript et exécuter des commandes de build, et non pour exécuter des applications Node.js en tant que serveur.

Accédez à l'espace client, section Hébergement, sélectionnez le service d'hébergement sur lequel vous voulez installer Node.js et ouvrez la section Gestionnaire de paquets.

Installation de Node.js

Si Node.js n'est pas installé, vous verrez une carte avec l'état Non installé et un interrupteur désactivé. Activez-le et le panneau de Node.js s'ouvrira avec les versions disponibles à ce moment-là.

Le panneau vous indique lui-même laquelle choisir si vous n'avez pas de préférence ; suivez cette recommandation, sauf si la propriété engines.node de votre package.json en exige une autre. Avant de décider, consultez aussi le cycle de vie officiel de Node.js : les étiquettes LTS et les dates de fin de support changent avec le temps, c'est pourquoi ce guide ne fixe pas de numéros de version.

Les versions EOL ne doivent pas être utilisées pour de nouveaux projets ni pour les déploiements habituels. Si le panneau en conserve une pour faciliter une migration, utilisez-la uniquement de façon temporaire, isolée et sans services persistants, avec une date définie pour mettre à jour les dépendances et retirer cet environnement.

Sélectionnez la version et cliquez sur Installer NVM et Node.js suivi du numéro de version. Le processus installe NVM (Node Version Manager), télécharge et installe Node.js, configure npm automatiquement, ajoute la configuration à votre .bashrc et vérifie l'installation. Une fois terminé, vous verrez un message de réussite avec les versions installées.

Changement de version

Dans la carte Node.js du Gestionnaire de paquets, cliquez sur Changer de version, sélectionnez la nouvelle et cliquez sur Passer à vX.x. Le système téléchargera la nouvelle version si elle n'est pas installée, la configurera par défaut et vérifiera qu'elle fonctionne correctement.

Changer de version affecte tous les projets du même service d'hébergement. Si vous avez besoin de versions différentes pour des projets distincts, utilisez nvm use manuellement dans vos scripts.

Exemples d'utilisation

L'installation de Node.js ajoute automatiquement la configuration nécessaire à votre .bashrc, ce qui rend Node.js disponible dans les sessions SSH interactives et dans l'exécuteur de commandes du panneau. En revanche, dans les scripts de déploiement personnalisés et les tâches cron, il faut activer NVM manuellement, car ces contextes ne chargent pas .bashrc automatiquement.

Les exemples de compilation supposent que package.json et package-lock.json se trouvent dans le dépôt et sont synchronisés. Installez ou mettez à jour les dépendances en développement, testez le résultat et enregistrez les deux fichiers. npm ci reconstruit node_modules selon le fichier de verrouillage ; --include=dev inclut les outils de build même si l'environnement est en production.

Depuis les scripts de déploiement

Le principal cas d'usage est de le combiner avec l'outil de déploiement automatique depuis GitHub. L'éditeur exécute une commande par ligne et chaque ligne ouvre son propre shell : activez NVM sur la même ligne que celle qui utilise npm ou npx, et non sur une ligne séparée.

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

Projet avec Tailwind CSS et sa CLI déjà déclarés comme dépendances :

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 avec un thème personnalisé :

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

Depuis SSH et l'exécuteur de commandes

Lorsque vous vous connectez en SSH de manière interactive ou que vous utilisez l'exécuteur de commandes du panneau de déploiement, Node.js est disponible automatiquement sans rien exporter. Il suffit de vous connecter en SSH ou d'utiliser l'exécuteur de commandes et de lancer directement :

Compiler les assets manuellement :

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

Compiler Tailwind CSS avec ses dépendances déjà déclarées :

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

Optimiser des images avec sharp, si le projet inclut cette dépendance et le script indiqué :

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

Exécuter les tests :

npm ci --include=dev
npm test

Compiler TypeScript, s'il est déclaré et configuré dans le projet :

npm ci --include=dev
npx tsc

Désinstallation

Désactivez l'interrupteur de la carte Node.js et confirmez dans Désinstaller Node.js. Cela supprime toutes les versions de Node.js, NVM, les paquets npm globaux enregistrés dans NVM et les lignes de configuration de NVM dans .bashrc. Les node_modules locaux de vos projets ne sont pas supprimés par cette action. Avant de désinstaller, vérifiez les déploiements et les tâches cron qui dépendent de Node.

Limitations importantes

Cet outil est conçu pour faciliter le déploiement en compilant des assets et en exécutant des commandes, et non pour exécuter des applications Node.js en tant que serveur. Les cas valides incluent la compilation de CSS/JavaScript avec PostCSS, Sass, Tailwind, Webpack, Vite ou Rollup, l'optimisation d'images, l'exécution de tests et la génération de documentation. Vous pouvez aussi héberger React, Vue ou un autre site statique connecté à une API externe : une fois compilé, l'hébergement ne fait que servir ses fichiers et le navigateur ou un backend PHP peuvent communiquer avec l'API en HTTPS.

Il n'est pas adapté aux serveurs Express, à Next.js en mode serveur, aux WebSockets ni aux API REST qui doivent s'exécuter en permanence. Pour ces cas, il vous faut un environnement qui accepte des processus Node persistants et gère leur publication HTTP, leur redémarrage et leurs ports. Installer Node depuis cette carte ne configure pas ce service ; vérifiez la compatibilité de votre projet avant de souscrire un autre environnement.

Les processus persistants des offres Avanza, Max et Elastic maintiennent actifs des workers de files d'attente, Horizon ou vos propres commandes, mais ils sont destinés aux tâches en arrière-plan : nous ne prenons pas en charge un serveur Node.js ni d'autres programmes qui écoutent sur un port. Si vous avez besoin de WebSockets pour une application Laravel, connectez-la à un service compatible Pusher, comme nous l'expliquons dans WebSockets dans Laravel.

Les commandes npm sont soumises aux limites de CPU et de RAM de l'offre d'hébergement, ainsi qu'aux durées maximales de l'exécuteur que vous utilisez. Si vos compilations demandent beaucoup de ressources, envisagez de compiler en local ou dans un système CI/CD et de n'envoyer que les assets compilés. Certains paquets npm qui nécessitent la compilation de code natif peuvent échouer s'ils requièrent des dépendances système non disponibles.

Résolution des problèmes

« NVM non trouvé » ou « npm command not found » dans les scripts de déploiement : incluez le chargement de NVM sur la même ligne que celle qui utilise npm ou npx, comme le montrent les exemples de déploiement. S'il n'apparaît pas non plus dans une session interactive, vérifiez que NVM a bien été chargé.

« npm command not found » en SSH interactif : vérifiez que Node.js est correctement installé dans le Gestionnaire de paquets. S'il est installé mais ne fonctionne pas, fermez puis rouvrez votre session SSH pour que .bashrc soit chargé, ou exécutez source ~/.bashrc.

Installation des paquets très lente : la première fois que vous exécutez npm install, cela peut prendre plusieurs minutes, car npm télécharge toutes les dépendances. Le cache peut réduire les téléchargements suivants, mais la compilation et les scripts d'installation continuent de consommer des ressources.

Erreur « EACCES: permission denied » lors de l'installation d'un paquet global : cela indique généralement que NVM n'est pas actif dans ce shell et que npm essaie d'écrire hors de votre compte. Activez NVM avec . "$HOME/.nvm/nvm.sh" et recommencez ; avec NVM, les paquets globaux s'installent dans $HOME/.nvm.

La version de Node.js ne correspond pas : si node --version affiche une version différente, assurez-vous d'avoir changé la version par défaut depuis le Gestionnaire de paquets ou utilisez nvm use VERSION pour changer temporairement.

Intégration avec d'autres outils

Vous pouvez utiliser Node.js avec le système de déploiement automatique depuis GitHub pour compiler les assets automatiquement à chaque déploiement sans les envoyer dans le dépôt. Vous pouvez combiner Composer et npm dans le même script de déploiement :

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

Vous pouvez aussi utiliser Node.js dans des tâches cron pour des tâches planifiées. Comme dans les scripts de déploiement, vous devez activer NVM manuellement, car les tâches cron ne chargent pas .bashrc :

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

Avant d'automatiser, lancez une compilation de test et vérifiez que le répertoire attendu est généré et que le site charge ses ressources.