Pas encore de site web à héberger ? Nous créons aussi votre site ou votre application. Voir les packs

KENN HOSTING
Tous les articles
Tutoriels

Déployer une application React sur cPanel

Aurel KENNE29 août 20268 min de lecture

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 :

  1. Le build de votre projet React en local
  2. L'envoi des fichiers buildés sur votre hébergement
  3. La configuration nécessaire pour que le routage interne de votre app (React Router) fonctionne correctement
  4. La gestion des variables d'environnement
  5. 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@latest avec le template React) : le build se trouve dans le dossier dist/

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.

  1. Connectez-vous à votre cPanel et ouvrez Gestionnaire de fichiers.
  2. Placez-vous dans le dossier où votre app doit être accessible :
    • public_html si l'app doit répondre sur https://votredomaine.com
    • public_html/mon-app si vous préférez https://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)
  3. Compressez le CONTENU de votre dossier build/ (ou dist/) en .zip en local, pas le dossier lui-même. C'est une erreur fréquente : si vous zippez le dossier build, vous obtiendrez public_html/build/index.html au lieu de public_html/index.html, et votre site ne s'affichera pas à la racine attendue.
cd build
zip -r ../deploiement.zip .
cd ..
  1. Dans le Gestionnaire de fichiers, cliquez sur Charger, sélectionnez deploiement.zip, attendez la fin de l'envoi.
  2. Une fois le fichier uploadé, faites un clic droit dessus puis Extraire. Choisissez le dossier courant comme destination.
  3. Supprimez le fichier .zip une 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 par REACT_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é.