Déployer une application React sur cPanel
Une app React en production, c'est juste des fichiers statiques
Avant de commencer, un point important qui évite beaucoup de confusion : une fois buildée, une application React n'est plus une application Node.js. C'est un ensemble de fichiers HTML, CSS et JavaScript statiques, exactement comme un site classique. Votre hébergement cPanel n'a donc besoin d'aucun runtime Node.js pour la servir, contrairement à une API Node.js/Express qui doit rester un processus actif en permanence (ce cas-là fait l'objet d'un autre article, pour déployer une API Node.js/Express sur cPanel).
Concrètement, ce guide couvre :
- Le build de votre projet React en local
- L'envoi des fichiers buildés sur votre hébergement
- La configuration nécessaire pour que le routage interne de votre app (React Router) fonctionne correctement
- La gestion des variables d'environnement
- Le rattachement de votre nom de domaine
Étape 1 : builder votre application en local
Le build se fait toujours sur votre machine (ou dans votre pipeline CI), jamais sur le serveur cPanel. Installez d'abord les dépendances si ce n'est pas déjà fait :
npm install
Puis lancez le build de production :
npm run build
Le dossier généré dépend de l'outil utilisé pour créer votre projet :
- Create React App : le build se trouve dans le dossier
build/ - Vite (
npm create vite@latestavec le template React) : le build se trouve dans le dossierdist/
Dans les deux cas, vous obtenez un index.html, un dossier assets/ ou static/ avec vos fichiers JS/CSS minifiés, et éventuellement d'autres fichiers statiques (favicon, images, manifest...). Vérifiez que ce dossier existe bien et contient un index.html avant de passer à l'étape suivante :
ls build/
# ou
ls dist/
Étape 2 : envoyer les fichiers sur votre hébergement
Via le Gestionnaire de fichiers cPanel
C'est la méthode la plus simple, sans rien installer en local.
- Connectez-vous à votre cPanel et ouvrez Gestionnaire de fichiers.
- Placez-vous dans le dossier où votre app doit être accessible :
public_htmlsi l'app doit répondre surhttps://votredomaine.compublic_html/mon-appsi vous préférezhttps://votredomaine.com/mon-app- le dossier racine d'un sous-domaine si vous préférez
https://app.votredomaine.com(le sous-domaine doit déjà exister, voir l'étape 5)
- Compressez le CONTENU de votre dossier
build/(oudist/) en.zipen local, pas le dossier lui-même. C'est une erreur fréquente : si vous zippez le dossierbuild, vous obtiendrezpublic_html/build/index.htmlau lieu depublic_html/index.html, et votre site ne s'affichera pas à la racine attendue.
cd build
zip -r ../deploiement.zip .
cd ..
- Dans le Gestionnaire de fichiers, cliquez sur Charger, sélectionnez
deploiement.zip, attendez la fin de l'envoi. - Une fois le fichier uploadé, faites un clic droit dessus puis Extraire. Choisissez le dossier courant comme destination.
- Supprimez le fichier
.zipune fois l'extraction terminée, il n'a plus d'utilité sur le serveur.
Vérifiez que index.html se trouve bien directement dans public_html (ou le dossier choisi), pas dans un sous-dossier imbriqué.
Via FTP
Si vous préférez un client FTP (FileZilla, Cyberduck...), récupérez vos identifiants FTP depuis votre espace client KennHosting, connectez-vous, puis glissez-déposez le CONTENU du dossier build//dist/ directement dans public_html (ou le dossier de destination choisi). Le principe est identique au Gestionnaire de fichiers : on transfère le contenu du dossier buildé, pas le dossier lui-même.
Étape 3 : faire fonctionner le routage côté client (React Router)
C'est l'étape la plus souvent oubliée, et celle qui provoque le plus de messages du type « mon app marche sur la page d'accueil mais pas si je rafraîchis une page interne ou que je partage un lien direct ».
Si votre application utilise React Router en mode BrowserRouter (le mode par défaut dans la grande majorité des projets), toutes vos routes internes (/produits, /produits/123, /compte...) n'existent QUE côté JavaScript, dans le navigateur. Quand un visiteur arrive directement sur https://votredomaine.com/produits/123 (lien partagé, favori, rafraîchissement de page), le navigateur demande ce chemin exact au serveur Apache. Apache cherche un fichier ou un dossier produits/123 sur le disque, ne le trouve pas, et renvoie une erreur 404, avant même que votre application React n'ait eu la chance de se charger.
La solution est de dire à Apache : « si le chemin demandé ne correspond à aucun fichier ou dossier réel, sers index.html à la place, et laisse React Router gérer l'affichage côté client ». Cela se fait avec un fichier .htaccess à placer à la racine du dossier où vous avez déployé votre app (le même dossier que votre index.html).
Créez (ou éditez, si un .htaccess existe déjà pour d'autres besoins) un fichier .htaccess avec ce contenu :
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
# Laisse passer les fichiers et dossiers qui existent réellement
RewriteCond %{REQUEST_FILENAME} -f [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^ - [L]
# Toute autre route est redirigée vers index.html
RewriteRule ^ index.html [L]
</IfModule>
Le module mod_rewrite est activé par défaut sur les hébergements KennHosting, vous n'avez rien d'autre à configurer côté serveur. Si votre app est déployée dans un sous-dossier (par exemple public_html/mon-app), adaptez RewriteBase en conséquence :
RewriteBase /mon-app/
Vous pouvez créer ce fichier directement depuis le Gestionnaire de fichiers cPanel (Fichier > Nouveau fichier, nommez-le .htaccess, puis éditez-le avec l'éditeur de code intégré). Pensez à activer l'affichage des fichiers cachés dans le Gestionnaire de fichiers (Paramètres > Afficher les fichiers cachés) si vous ne le voyez pas apparaître après création.
Étape 4 : variables d'environnement
Contrairement à une application serveur, React intègre ses variables d'environnement AU MOMENT DU BUILD, pas au moment de l'exécution. Il n'y a donc rien à configurer côté cPanel pour cette partie : tout se joue avant l'étape 1.
- Avec Create React App, créez un fichier
.envà la racine de votre projet local, avant le build, avec des variables préfixées parREACT_APP_:
REACT_APP_API_URL=https://api.votredomaine.com
- Avec Vite, le préfixe attendu est
VITE_:
VITE_API_URL=https://api.votredomaine.com
Dans les deux cas, ces valeurs sont injectées directement dans le code JavaScript généré par npm run build. Si vous changez une variable d'environnement, vous devez rebuilder et redéployer, un simple redémarrage ne suffit pas (il n'y a d'ailleurs rien à redémarrer, puisque ce sont des fichiers statiques).
Ne mettez jamais de secret sensible (clé API privée, mot de passe) dans ces variables : elles finissent en clair dans le JavaScript téléchargé par n'importe quel visiteur. Réservez-les à des informations qui peuvent être publiques, comme l'URL de votre API.
Étape 5 : rattacher votre nom de domaine
Si votre domaine est le domaine principal de votre hébergement, il pointe déjà vers public_html : déployer directement dedans suffit, votre app sera accessible immédiatement à l'adresse de votre domaine.
Si vous préférez utiliser un sous-domaine (app.votredomaine.com) ou un domaine additionnel dédié à cette application, vous devez d'abord le créer depuis votre cPanel avant de pouvoir y déployer quoi que ce soit. La création d'un sous-domaine et la gestion des domaines additionnels sont déjà détaillées dans notre documentation, consultez l'article correspondant dans la base de connaissances si vous n'avez pas encore créé ce sous-domaine.
Mettre à jour votre application
À chaque nouvelle version de votre code, le processus est le même : rebuild en local, puis remplacement des fichiers sur le serveur. Il n'y a pas de mécanisme de déploiement automatique depuis cPanel pour une app statique : vous répétez les étapes 1 et 2 à chaque mise à jour.
Un conseil pratique : avant d'écraser les fichiers existants, gardez une sauvegarde locale de votre ancien build (ou gardez l'ancien zip) le temps de vérifier que la nouvelle version fonctionne bien, pour pouvoir revenir en arrière rapidement en cas de souci.
Récapitulatif
# En local
npm install
npm run build
cd build # ou dist
zip -r ../deploiement.zip .
cd ..
Puis dans cPanel : Gestionnaire de fichiers → upload du zip dans public_html → extraction → suppression du zip → vérification/ajout du .htaccess pour le routage côté client.
Votre application React est maintenant en ligne, avec un routage interne qui fonctionne même sur rafraîchissement de page ou lien partagé.
Articles liés
Déployer une API Node.js/Express sur cPanel
Guide complet pour déployer une API Node.js/Express sur votre hébergement cPanel, avec l'outil Setup Node.js App : création de l'application, installation des dépendances, variables d'environnement et redémarrage.
Déployer une application Laravel ou Symfony sur cPanel
Laravel et Symfony ont tous les deux un dossier public/ qui doit devenir la racine servie par le serveur. Voici comment bien le configurer sur votre hébergement cPanel, étape par étape.
Déployer une application Python (Django ou Flask) sur cPanel
Guide complet pour déployer une application Python (Django ou Flask) sur votre hébergement cPanel, avec Setup Python App, virtualenv et configuration WSGI.
Déployer React + Express.js + MySQL sur cPanel (Guide Complet)
Guide complet pour déployer une application React, Express.js et MySQL sur cPanel.
