Comment installer React.js sur un VPS Windows : Guide de configuration complet

React.js est une bibliothèque JavaScript open-source maintenue par Meta (anciennement Facebook) pour créer des interfaces utilisateur basées sur des composants, en particulier des applications monopages (SPAs) qui mettent à jour le DOM dynamiquement sans rechargement complet de la page. Installer React sur un VPS Windows — plutôt que sur un poste de travail local — vous offre un environnement de développement persistant et accessible à distance avec des ressources dédiées, ce qui le rend idéal pour la collaboration en équipe, les pipelines CI/CD et les déploiements de staging.

Ce guide détaille chaque étape d’une installation React.js de qualité production sur un VPS Windows : de la configuration du runtime Node.js et de la gestion des variables d’environnement à la création de projets, au fonctionnement du serveur de développement et à la génération de builds de production. Il couvre également les modes d’échec non évidents qui piègent les ingénieurs qui suivent des tutoriels superficiels.

Pourquoi installer React sur un VPS Windows plutôt qu’en local

Exécuter votre environnement de développement React sur une instance VPS Hosting plutôt que sur une machine locale résout plusieurs problèmes concrets :

• Disponibilité permanente : Le serveur de développement reste actif même lorsque votre machine locale est éteinte, permettant aux membres distants de l’équipe ou aux testeurs QA d’accéder à une URL de prévisualisation en direct à tout moment.
• Environnement cohérent : Chaque développeur se connecte au même OS, à la même version de Node et au même arbre de dépendances, éliminant les bugs du type « ça marche sur ma machine ».
• Isolation des ressources : Les builds gourmands en CPU (npm run build, grandes compilations Webpack) ne dégradent pas votre poste de travail local.
• Parité de staging : Un VPS Windows reflète l’environnement de déploiement cible lorsque votre stack de production est également basée sur Windows Server (IIS, architectures hybrides ASP.NET).
• Accessibilité à distance : Vous pouvez exposer le serveur de développement sur un port spécifique et y accéder depuis n’importe quel navigateur, où que vous soyez.

Si votre charge de travail évolue vers la diffusion d’assets React compilés aux côtés d’une API Node.js, envisagez de passer à un environnement Dedicated Servers pour un débit I/O garanti et sans effets de voisinage bruyant.

Prérequis

Avant de commencer, confirmez que les éléments suivants sont en place sur votre VPS Windows :

• Windows Server 2016 / 2019 / 2022 ou Windows 10/11 (64 bits)
• Accès administrateur ou utilisateur élevé via RDP
• Accès internet sortant sur le VPS (pour télécharger les installateurs et les packages npm)
• Au moins 2 GB RAM — la compilation en mémoire de Webpack est gourmande en mémoire ; 4 GB est recommandé pour les projets avec plus de quelques dépendances
• Un éditeur de texte ou IDE — Visual Studio Code est la référence de facto pour le développement React

Étape 1 : Installer Node.js sur Windows

1.1 Télécharger la version LTS

React ne nécessite pas la toute dernière version de Node.js. Le canal LTS (Long Term Support) est le bon choix pour tout environnement où la stabilité est importante.

1. Ouvrez un navigateur sur votre VPS (ou téléchargez à distance et transférez via le presse-papiers RDP).
2. Accédez à https://nodejs.org.
3. Téléchargez le Windows Installer (.msi) pour la version LTS actuelle (par exemple, 20.x ou 22.x).

Note critique : Téléchargez toujours l’installateur .msi 64 bits, et non l’archive .zip. Le .msi gère automatiquement l’enregistrement du PATH, l’intégration des services et la dépendance Visual C++ Redistributable. L’archive .zip nécessite une configuration manuelle du PATH et est une source courante d’erreurs de non-reconnaissance de npm.

1.2 Exécuter l’installateur

Exécutez le fichier .msi téléchargé et suivez l’assistant :

1. Acceptez le contrat de licence.
2. Laissez le chemin de destination par défaut (C:Program Filesnodejs) sauf si vous avez une raison spécifique de le modifier.
3. Sur l’écran Configuration personnalisée, assurez-vous que tous les composants suivants sont cochés :

• Runtime Node.js
• Gestionnaire de packages npm
• Ajouter au PATH (c’est la case à cocher la plus importante — si elle n’est pas cochée, aucun terminal ne reconnaîtra node ou npm)
• Raccourcis vers la documentation en ligne (optionnel)

1. Sur l’écran Outils pour les modules natifs, cochez « Installer automatiquement les outils nécessaires » si vous prévoyez d’utiliser des packages npm nécessitant une compilation native (node-gyp, bcrypt, sharp, etc.). Cela installe silencieusement Chocolatey, Python et les Visual Studio Build Tools.
2. Terminez l’installation et redémarrez la session terminal (ou toute la session RDP si les modifications du PATH ne sont pas immédiatement reflétées).

1.3 Vérifier l’installation

Ouvrez une nouvelle fenêtre PowerShell ou Invite de commandes (pas celle qui était ouverte avant l’installation — elle n’aura pas le PATH mis à jour) et exécutez :

node -v

npm -v

Les deux commandes doivent retourner des chaînes de version. Si l’une d’elles retourne 'node' is not recognized as an internal or external command, le PATH n’a pas été correctement défini. Consultez la section de dépannage ci-dessous.

Exemple de sortie attendue :

v20.14.0
10.7.0

1.4 Configurer le répertoire des packages globaux de npm (Optionnel mais recommandé)

Par défaut, npm installe les packages globaux dans C:Users<username>AppDataRoamingnpm. Sur un environnement Windows Server partagé ou multi-utilisateurs, cela peut provoquer des conflits de permissions. Pour définir un répertoire global personnalisé :

npm config set prefix "C:npm-global"

Ajoutez ensuite C:npm-global au PATH système via Propriétés système > Variables d’environnement > Variables système > Path.

Étape 2 : Créer une application React

2.1 L’approche moderne : Vite (recommandé plutôt que Create React App)

L’article original recommande create-react-app (CRA). C’est un conseil obsolète. CRA a été officiellement déprécié début 2023 et n’est plus maintenu par l’équipe principale de React. La documentation React elle-même ne le recommande plus pour les nouveaux projets.

Les outils de création de projets actuellement recommandés sont :

Pour une SPA simple sur un VPS Windows, Vite est le bon choix en 2024 et au-delà.

2.2 Créer un nouveau projet React avec Vite

Ouvrez PowerShell et naviguez vers votre répertoire de projets :

cd C:Projects

Créez un nouveau projet React :

npm create vite@latest my-react-app -- --template react

Pour utiliser TypeScript (fortement recommandé pour tout projet non trivial) :

npm create vite@latest my-react-app -- --template react-ts

Naviguez dans le répertoire du projet et installez les dépendances :

cd my-react-app
npm install

2.3 Si vous devez utiliser Create React App (projets legacy)

Si vous maintenez une base de code legacy qui nécessite CRA, utilisez npx pour l’exécuter sans installation globale :

npx create-react-app my-react-app

N’exécutez pas npm install -g create-react-app. L’approche d’installation globale est dépréciée et récupérera une version mise en cache obsolète. L’utilisation de npx récupère toujours la dernière version disponible depuis le registre.

Étape 3 : Démarrer le serveur de développement

3.1 Démarrer le serveur de développement

Pour un projet basé sur Vite :

npm run dev

Pour un projet basé sur CRA :

npm start

Les deux commandes démarrent un serveur de développement local. Vite utilise par défaut http://localhost:5173 ; CRA utilise par défaut http://localhost:3000.

3.2 Exposer le serveur de développement sur un VPS Windows (accès à distance)

Sur une machine locale, le serveur de développement n’est accessible que depuis localhost. Sur un VPS, vous souhaitez généralement y accéder depuis votre navigateur local via internet. Deux modifications sont nécessaires :

Lier le serveur à toutes les interfaces réseau :

Pour Vite, modifiez vite.config.js (ou vite.config.ts) :

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    host: '0.0.0.0',
    port: 5173,
  },
})

Pour CRA, définissez la variable d’environnement HOST avant le démarrage :

set HOST=0.0.0.0
npm start

Ouvrir le port dans le pare-feu Windows :

netsh advfirewall firewall add rule name="React Dev Server" dir=in action=allow protocol=TCP localport=5173

Après cela, vous pouvez accéder au serveur de développement à l’adresse http://<your-vps-ip>:5173 depuis n’importe quel navigateur.

Avertissement de sécurité : N’exposez jamais un serveur de développement sur l’internet public d’un VPS de production sans authentification. Utilisez un reverse proxy (Nginx ou IIS avec URL Rewrite) ou un tunnel VPN pour tout environnement manipulant des données réelles.

Étape 4 : Structure du projet et fichiers clés

Comprendre la structure générée évite toute confusion lorsque vous commencez à modifier des fichiers :

my-react-app/
├── public/             # Static assets served as-is (favicon, robots.txt)
├── src/
│   ├── assets/         # Images, fonts imported by components
│   ├── App.jsx         # Root component
│   ├── App.css         # Root component styles
│   ├── main.jsx        # Entry point — mounts <App /> into index.html
│   └── index.css       # Global styles
├── index.html          # HTML shell — Vite injects the bundle here
├── vite.config.js      # Vite configuration
├── package.json        # Dependencies and scripts
└── node_modules/       # Installed packages (never commit this)

Le fichier src/main.jsx est le point d’entrée de l’application. Il appelle ReactDOM.createRoot() pour monter le composant racine dans la div #root de index.html. Chaque composant que vous créez sera finalement importé dans cet arbre.

Étape 5 : Construire pour la production

Lorsque l’application est prête pour le déploiement, générez un build statique optimisé :

npm run build

Cette commande invoque le bundler basé sur Rollup de Vite (ou Webpack pour CRA), qui :

• Transpile JSX et le JavaScript moderne vers ES5/ES2015+ compatible avec les navigateurs
• Effectue le tree-shaking du code inutilisé dans le bundle
• Minifie JavaScript, CSS et HTML
• Génère des noms de fichiers avec hash de contenu pour la mise en cache longue durée des navigateurs
• Génère tout dans le répertoire dist/ (Vite) ou build/ (CRA)

Pour prévisualiser le build de production localement avant le déploiement :

npm run preview

Le contenu de dist/ est constitué de fichiers purement statiques (HTML, JS, CSS, assets). Ils peuvent être servis par n’importe quel serveur web — IIS sur Windows Server, Nginx, Apache ou un service d’hébergement statique.

Déployer le build sur IIS sous Windows Server

Si votre VPS exécute IIS, configurez un nouveau site pointant vers le dossier dist/. Comme les SPAs React utilisent le routage côté client, vous devez ajouter une règle URL Rewrite pour rediriger tous les 404 vers index.html :

<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="React SPA" stopProcessing="true">
          <match url=".*" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          </conditions>
          <action type="Rewrite" url="/index.html" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

Sans cette règle, toute navigation directe vers une route comme /dashboard retournera une erreur 404 d’IIS au lieu de charger l’application React.

Si vous servez le frontend React aux côtés d’une API backend et avez besoin d’un environnement de panneau de contrôle géré, un VPS avec cPanel peut simplifier la configuration des hôtes virtuels et la terminaison SSL.

Étape 6 : Sécuriser l’application avec HTTPS

Une application React en production doit être servie via HTTPS. Les navigateurs bloquent les requêtes à contenu mixte, et de nombreuses API navigateur (service workers, géolocalisation, presse-papiers) sont limitées aux contextes sécurisés.

Pour un déploiement hébergé sur VPS :

1. Obtenez un certificat SSL pour votre domaine. AlexHost propose des Certificats SSL qui peuvent être installés directement sur votre VPS.
2. Configurez IIS ou votre reverse proxy pour terminer TLS sur le port 443 et rediriger HTTP (port 80) vers HTTPS.
3. Définissez la variable d’environnement HTTPS sur true si vous utilisez le serveur intégré de CRA pour les tests HTTPS locaux.

Si vous n’avez pas encore de domaine pointant vers votre VPS, enregistrez-en un d’abord via l’Enregistrement de domaine et configurez l’enregistrement DNS A pour pointer vers l’adresse IP de votre VPS.

Étape 7 : Résolution des problèmes courants

node ou npm non reconnu

Cela signifie que le répertoire d’installation de Node.js n’est pas dans le PATH système. Corrigez-le manuellement :

1. Appuyez sur Win + R, tapez sysdm.cpl, appuyez sur Entrée.
2. Allez dans Avancé > Variables d’environnement.
3. Sous Variables système, trouvez Path et cliquez sur Modifier.
4. Ajoutez C:Program Filesnodejs comme nouvelle entrée.
5. Cliquez sur OK dans toutes les boîtes de dialogue, puis ouvrez une nouvelle fenêtre de terminal.

Erreurs EACCES ou Permission refusée lors de l’installation npm

Sur Windows Server, cela se produit généralement lors de l’exécution de npm en tant qu’utilisateur restreint. Exécutez PowerShell en tant qu’Administrateur, ou configurez le cache npm et les répertoires globaux vers un chemin appartenant à l’utilisateur actuel :

npm config set cache "C:npm-cache"
npm config set prefix "C:npm-global"

Port déjà utilisé

Si le port 5173 ou 3000 est occupé par un autre processus :

netstat -ano | findstr :5173

Identifiez le PID dans la dernière colonne, puis :

taskkill /PID <PID> /F

Vous pouvez également changer le port dans vite.config.js ou passer --port comme indicateur :

npm run dev -- --port 3001

npm ERR! code EINTEGRITY (Incompatibilité de somme de contrôle)

Cela indique un cache npm corrompu. Videz-le et réessayez :

npm cache clean --force
npm install

npm install lent lors de la première exécution

L’installation initiale des dépendances pour un projet React peut prendre 2 à 5 minutes selon le débit réseau du VPS et les I/O disque. Si cela expire systématiquement, vérifiez si le VPS dispose d’un accès sortant vers registry.npmjs.org sur le port 443. Certaines politiques de pare-feu de datacenter bloquent cela par défaut.

Matrice de décision : Choisir la bonne configuration React pour votre VPS

Liste de contrôle des points clés pratiques

• Installez la version LTS de Node.js en utilisant l’installateur .msi, et non l’archive .zip, pour garantir l’enregistrement automatique du PATH.
• Utilisez npx create vite@latest pour tous les nouveaux projets React — CRA est déprécié et ne doit pas être utilisé pour le développement de nouveaux projets.
• Sur un VPS, définissez host: '0.0.0.0' dans vite.config.js et ouvrez le port de pare-feu correspondant pour accéder au serveur de développement à distance.
• Ajoutez une règle URL Rewrite IIS pour rediriger toutes les requêtes non-fichier et non-répertoire vers index.html — sans elle, le routage côté client se brise lors d’un accès direct par URL.
• Servez toujours les builds de production via HTTPS ; obtenez et installez un certificat SSL avant la mise en ligne.
• Exécutez npm run build et inspectez la sortie dist/ avant le déploiement — vérifiez les tailles des bundles en utilisant npm run build -- --report ou vite-bundle-visualizer.
• Ne commitez jamais node_modules/ dans le contrôle de version ; ajoutez-le toujours à .gitignore.
• Si plusieurs versions de Node sont requises pour différents projets, installez nvm-windows pour les gérer sans réinstaller Node.js globalement.

FAQ

React.js doit-il être « installé » sur un serveur, ou seulement la sortie du build ?

React lui-même est une dépendance de build. La sortie de production de npm run build est du HTML, CSS et JavaScript ordinaires — aucun runtime Node.js n’est requis sur le serveur pour le servir. Node.js n’est nécessaire que sur la machine où vous exécutez le processus de build.

Quelle est la différence entre npm run dev et npm run build ?

npm run dev démarre un serveur de développement avec le remplacement de module à chaud (HMR) et des source maps non minifiées — il n’est pas optimisé pour les performances et ne doit jamais être utilisé pour servir du trafic en production. npm run build produit un bundle statique minifié, tree-shaké et avec hash de contenu, destiné au déploiement.

Pourquoi Create React App est-il déprécié et que dois-je utiliser à la place ?

CRA repose sur Webpack 4, qui présente des temps de build et de HMR significativement plus lents comparés au serveur de développement natif ESM de Vite. L’équipe React a officiellement retiré CRA de leur documentation en 2023 et recommande désormais Vite pour les SPAs, Next.js pour les applications full-stack et Remix pour les applications à forte charge de données.

Puis-je exécuter plusieurs projets React sur le même VPS Windows simultanément ?

Oui. Chaque projet exécute son serveur de développement sur un port différent. Configurez le vite.config.js de chaque projet avec une valeur port unique, ouvrez chaque port dans le pare-feu Windows et configurez optionnellement IIS comme reverse proxy pour router les sous-domaines ou chemins vers le port approprié.

Comment maintenir le serveur de développement React actif après la fermeture de ma session RDP ?

Utilisez un gestionnaire de processus. Installez PM2 globalement (npm install -g pm2) et démarrez le serveur de développement comme processus géré : pm2 start npm --name "react-dev" -- run dev. PM2 maintient le processus actif indépendamment de la session terminal et peut être configuré pour redémarrer au démarrage du système.