Hébergement Web

Comment déployer une application Node.js sur Plesk ?

Déployez votre application Node.js ou Next.js sur votre hébergement web Plesk Winheberg, configuration automatique, protection des sources, version LTS, dépendances, build, variables et secrets.

1 novembre 2026 Winheberg
Documentation›Hébergement Web›Comment déployer une application Node.js sur Plesk ?

Contexte

L'hébergement web Winheberg fonctionne sous Plesk et prend en charge les applications Node.js, qu'il s'agisse d'une API, d'un backend ou d'un projet Next.js. Le déploiement diffère de celui d'un site PHP classique, car l'application tourne dans son propre processus géré par Phusion Passenger, et non comme un ensemble de fichiers servis directement par le serveur web.

Dès que vos fichiers sont en place, Plesk lit votre package.json, reconnaît le type d'application et propose une configuration automatique. Elle génère le fichier de démarrage attendu par Passenger et vous montre la liste des changements avant de les appliquer.

Ce guide suit ce parcours automatique, puis détaille la configuration manuelle pour les cas où la détection n'aboutit pas.

Prérequis

L'accès SSH n'est pas disponible sur les hébergements web. Toutes les opérations décrites ici se font depuis l'interface Plesk, y compris les commandes npm.

1. Tester le projet en local

Avant tout envoi, vérifiez que votre application se construit et démarre sur votre machine.

npm install
npm run build
npm run start

Si l'une de ces commandes échoue en local, elle échouera également sur le serveur. Corrigez avant de continuer, le diagnostic est bien plus simple sur votre poste. Si votre projet n'a pas d'étape de build, seules la première et la dernière commande vous concernent.

2. Envoyer les fichiers de l'application

Compressez vos sources dans une archive .zip, sans les dossiers node_modules et .next. Ces dossiers seront régénérés sur le serveur, et leur envoi provoque des incompatibilités de plateforme en plus d'un transfert inutilement long.

Ouvrez Fichiers dans le menu latéral, placez-vous dans httpdocs, cliquez sur + puis Téléverser le fichier. Une fois l'archive envoyée, sélectionnez-la et extrayez-la sur place depuis le menu Archive.

Menu Téléverser le fichier du gestionnaire de fichiers Plesk dans httpdocs

Vérifiez qu'à la fin de l'extraction, le fichier package.json se trouve bien directement dans httpdocs et non dans un sous-dossier intermédiaire.

L'ordre de ces étapes compte. Plesk ne détecte le type d'application et ne propose la configuration automatique que si package.json est déjà en place. Sur un domaine vide, vous devrez tout renseigner à la main.

3. Lancer la configuration automatique

Depuis Sites Web & Domaines, ouvrez votre domaine, l'onglet Démarrer, puis Node.js. Plesk affiche le Type d'application détecté depuis package.json et le bouton Configurer automatiquement.

Type d'application détecté et bouton Configurer automatiquement dans Node.js

Cliquez sur Configurer automatiquement. Plesk liste ce qu'il va modifier avant de rien appliquer, par exemple la création du fichier de démarrage .plesk.startup.cjs qui charge votre point d'entrée, et la mise de côté d'un index.html statique qui serait servi à la place de votre application.

Fenêtre Configurer automatiquement l'hébergement avec le bouton Appliquer et redémarrer

Relisez cette liste, puis cliquez sur Appliquer et redémarrer. Le fichier index.html d'origine est conservé sous le nom index.html.autoconfig-bak.

Inutile de changer le port écrit dans votre code. Passenger intercepte l'appel listen() de votre application et la branche sur son propre canal, quel que soit le port indiqué. Le fichier .plesk.startup.cjs le précise en commentaire, ne le modifiez pas et ne le supprimez pas.

4. Protéger vos fichiers source

Avec la configuration automatique, la Racine du document reste souvent la même que la Root d'application, c'est-à-dire /httpdocs. Le serveur web sert alors directement tout fichier présent dans ce dossier, y compris package.json et le code de votre application, que n'importe qui peut télécharger en connaissant son nom.

Plesk le rappelle d'ailleurs sur le tableau de bord tant que Node.js n'est pas activé, il recommande de définir la racine du document dans un sous-répertoire de la racine de l'application, par exemple public/.

Créez un dossier public dans httpdocs depuis le gestionnaire de fichiers. Sur le tableau de bord Node.js, cliquez ensuite sur l'icône de dossier à côté de Racine du document, sélectionnez public sous httpdocs dans l'arborescence, puis Enregistrer. Placez dans ce dossier uniquement les fichiers destinés à être servis tels quels, comme les images ou les feuilles de style.

N'écrivez jamais un mot de passe ou une clé d'API en dur dans votre code. Utilisez les Secrets de l'onglet Environnement, décrits à l'étape 8.

5. Vérifier la version et le mode d'application

Une fois la configuration appliquée, le tableau de bord affiche les boutons Redémarrer l'app, Arrêter l'app et Désactiver Node.js. Si le bouton Activer Node.js est encore présent, cliquez dessus.

Cliquez ensuite sur le crayon à côté de Version de Node.js, choisissez la version que réclame votre projet, puis Enregistrer. Contrôlez au passage que Mode d'application est bien sur production, c'est ce réglage qui fixe les variables NODE_ENV et PASSENGER_APP_ENV de votre application.

Sélecteur de version de Node.js et mode d'application production

Quelle version choisir

Les versions proposées ne se valent pas. Une version LTS reçoit des correctifs de sécurité pendant plusieurs années, alors que les versions impaires comme 23.x ou 21.x ne sont jamais passées en LTS et ne sont plus maintenues.

Versions de Node.js proposées par Plesk, statut au 1er novembre 2026
Version Statut Fin de support
26.x LTS actif depuis le 28 octobre 2026 30 avril 2029
24.x LTS en maintenance depuis le 20 octobre 2026 30 avril 2028
23.x Plus maintenue 1er juin 2025
22.x LTS en maintenance 30 avril 2027
21.x Plus maintenue 1er juin 2024
20.x Plus maintenue 30 avril 2026
18.x Plus maintenue 30 avril 2025

Retenez une version 26.x pour un nouveau projet, c'est la branche LTS active. Gardez 24.x si l'une de vos dépendances n'est pas encore compatible, elle reste corrigée jusqu'en avril 2028.

Les branches 23.x, 21.x, 20.x et 18.x ne reçoivent plus de correctifs de sécurité. Évitez-les pour une application exposée sur Internet, même si votre code fonctionne avec.

Une version trop ancienne fait par ailleurs échouer le build de la plupart des frameworks récents, avec un message qui ne mentionne pas toujours la version en cause. Next.js 16 réclame par exemple Node.js 20.9 au minimum.

6. Installer les dépendances

Cliquez sur Installer NPM, ou ouvrez l'onglet Exécuter les commandes Node.js et choisissez install dans la liste. Plesk lit votre package.json et reconstruit le dossier node_modules sur le serveur.

Onglet Exécuter les commandes Node.js avec la liste des scripts et commandes npm

La Sortie de la commande affiche le résultat. Attendez la fin de l'opération avant de passer à la suite, sur un projet volumineux l'installation prend plusieurs minutes.

Sortie de la commande npm install dans Plesk

Plesk prend aussi en charge Yarn et pnpm. Cliquez sur le crayon à côté de Gestionnaire de packages sur le tableau de bord pour choisir npm, yarn ou pnpm.

7. Lancer le build

Cliquez sur Démarrer le script. Plesk ouvre l'onglet Exécuter les commandes Node.js, dont la liste Scripts du package.json reprend les scripts de votre projet. Choisissez run build.

Pour un projet Next.js, cette étape génère le dossier .next, celui que vous n'avez volontairement pas envoyé. Construire sur le serveur plutôt que d'envoyer un build fait sur votre machine évite les incompatibilités d'architecture.

Pour Next.js, cette étape est obligatoire. Démarrer l'application sans build produit l'erreur Could not find a production build in the '.next' directory.

8. Déclarer les variables d'environnement

Ouvrez l'onglet Environnement. Il distingue deux types de valeurs transmises à votre application.

Onglet Environnement de Node.js avec les variables d'environnement et les secrets
Variables de l'onglet Environnement
Section Usage
Variables d'environnement Les réglages sans caractère sensible, visibles par toute personne qui ouvre cette page
Secrets Les mots de passe, clés d'API et jetons, stockés chiffrés et en écriture seule, leur valeur n'est plus jamais affichée après l'enregistrement
Variables prédéfinies NODE_ENV, PASSENGER_APP_ENV, NODE_PATH et IN_PASSENGER, définies par Passenger, une variable du même nom déclarée plus haut prend le dessus

Ajoutez vos valeurs avec Ajouter un champ, cliquez sur Enregistrer, puis sur Redémarrer l'app depuis le tableau de bord pour que l'application les prenne en compte.

Avec Next.js, les variables préfixées NEXT_PUBLIC_ sont intégrées au code au moment du build. Placez-les dans un fichier .env.production à la racine de l'application avant de lancer l'étape 7, et réservez-y uniquement des valeurs que vous acceptez de rendre publiques.

9. Démarrer l'application

Cliquez sur Redémarrer l'app, puis ouvrez votre domaine dans un navigateur. Tant que personne ne l'a visitée, le Statut indique Inactif, l'application démarre à la première requête. Il passe ensuite à En cours d'exécution, avec le nombre de processus et l'heure de démarrage.

Tableau de bord Node.js actif avec les boutons Redémarrer l'app, Installer NPM et Démarrer le script

Configurer manuellement

Si votre package.json n'était pas en place au moment de l'activation, ou si la détection n'a pas reconnu votre projet, renseignez les champs vous-même depuis le tableau de bord Node.js.

Champs à renseigner
Champ Valeur Rôle
Root d'application /httpdocs Le dossier qui contient le package.json
Racine du document /httpdocs/public Le dossier des fichiers servis tels quels, distinct de vos sources
Fichier de démarrage d'application Le fichier que Passenger exécute, app.js par défaut Le point d'entrée de votre application

Passenger démarre un fichier JavaScript, il ne lance pas npm start. Lorsqu'une application se lance habituellement par une commande npm, ouvrez le package.json et repérez le fichier passé à node, c'est celui-là qu'il faut déclarer. Pour une application Express ou tout code Node.js écrit à la main, ce fichier existe déjà, souvent app.js, server.js ou index.js.

Pour Next.js, il n'existe pas. La commande next start appelle un binaire du framework et non un fichier de votre projet. Créez donc un fichier start.js à la racine de votre application, avec ce contenu.

process.env.NODE_ENV = 'production';

const app = require('next/dist/cli/next-start');

app.nextStart({
  port: process.env.PORT || 3000,
});

Déclarez ensuite start.js dans Fichier de démarrage d'application, puis cliquez sur Redémarrer l'app.

Si votre package.json contient "type": "module", l'instruction require ci-dessus échoue. Nommez alors votre fichier start.cjs au lieu de start.js, l'extension .cjs force l'interprétation en CommonJS, puis déclarez ce nom dans le champ du fichier de démarrage.

En cas de problème

❌ Could not find a production build in the '.next' directory

Le build n'a pas été exécuté, ou il a échoué sans que vous l'ayez remarqué.

  • Relancez run build depuis Démarrer le script et lisez la Sortie de la commande jusqu'au bout
  • Vérifiez que le dossier .next existe dans la racine de l'application
  • Contrôlez que Root d'application pointe bien sur le dossier contenant le package.json

❌ require() of ES Module is not supported

Votre projet est déclaré en module ES, ce qui rend l'instruction require inutilisable dans un fichier de démarrage en .js.

  • Renommez votre fichier de démarrage avec l'extension .cjs
  • Reportez ce nouveau nom dans Fichier de démarrage d'application
  • Redémarrez l'application avec Redémarrer l'app

❌ The application process exited prematurely

Le processus n'a pas réussi à démarrer.

  • Vérifiez que le fichier de démarrage existe réellement à la racine de l'application
  • Assurez-vous que les dépendances ont bien été installées, la Sortie de la commande de install ne doit afficher aucune erreur
  • Recherchez une variable d'environnement ou un secret manquant dans l'onglet Environnement
  • Confirmez que Mode d'application est bien réglé sur production

❌ Vos fichiers source s'affichent dans le navigateur

La Racine du document est la même que la Root d'application, le serveur web sert donc vos sources directement.

  • Créez un dossier public dans la racine de l'application
  • Définissez /httpdocs/public comme Racine du document depuis le tableau de bord Node.js
  • Redémarrez l'application, puis ouvrez votre site en ajoutant /package.json à la fin de son adresse, le fichier ne doit plus s'afficher

Bonnes pratiques

  • Envoyez vos fichiers avant d'ouvrir la page Node.js, c'est ce qui permet la détection et la configuration automatique
  • Validez toujours npm run build en local avant d'envoyer quoi que ce soit
  • Gardez node_modules et .next hors de vos envois, ils se régénèrent côté serveur
  • Relancez le build puis Redémarrer l'app après chaque mise à jour de votre code
  • Restez sur une version LTS de Node.js et changez de branche avant sa fin de support
  • Rangez les mots de passe et clés d'API dans les Secrets, jamais dans le code ni dans un fichier servi par le site
  • Si vous changez de framework, relancez Configurer automatiquement pour que Plesk régénère le fichier de démarrage
  • Servez votre application en HTTPS avec le certificat gratuit décrit dans notre guide Comment générer un certificat SSL Let's Encrypt pour votre site web ?
  • Pour confier le déploiement à un développeur sans lui ouvrir tout votre compte, créez-lui un accès dédié avec notre guide Comment créer un utilisateur dans Plesk ?

Besoin d'aide ?

Si votre application ne démarre toujours pas après ces vérifications, ouvrez un ticket auprès de notre support depuis votre espace client, département Technique, en renseignant le champ Produit lié avec l'hébergement concerné.

Joignez le message d'erreur complet ainsi que la sortie du build. Notre équipe peut également consulter le journal de Passenger côté serveur, qui contient souvent la cause exacte d'un démarrage avorté.

Votre application est en ligne 🚀

Besoin d'un serveur Hébergement Web ?

Découvrez nos offres adaptées à vos besoins et lancez-vous dès maintenant.

Voir les offres