Build et déploiement d'une application React (Vite)

Déployer une application React construite avec Vite, c'est lancer npm run build, qui produit dans dist/ des fichiers statiques (une page HTML, du JavaScript et du CSS optimisés), puis les publier sur n'importe quel serveur web ou hébergeur statique. Deux réglages font la différence entre une mise en ligne qui marche et une page blanche : les variables d'environnement fixées au moment du build, et la redirection de toutes les adresses vers index.html pour que le routeur fonctionne. Ce chapitre construit AppliFrais pour la production et la déploie de plusieurs façons.

Construire la version de production

npm run build

Le script lance deux commandes : tsc -b vérifie les types de tout le projet (une erreur TypeScript arrête le build), puis vite build produit la version optimisée :

vite v8.3.5 building client environment for production...
✓ 163 modules transformed.
dist/index.html                   0.46 kB │ gzip:   0.29 kB
dist/assets/index-DG3HAu6L.css    0.27 kB │ gzip:   0.20 kB
dist/assets/index-CGeL-Yyg.js   360.58 kB │ gzip: 112.55 kB
✓ built in 349ms

Ce que fait le build :

• regroupe tous les modules (ton code, React, React Router, TanStack Query) en quelques fichiers ;
• retire ce qui ne sert pas (le code mort, les types TypeScript, les avertissements de développement de React) ;
• minifie le code (noms courts, espaces retirés) ;
• ajoute une empreinte au nom de chaque fichier (index-CGeL-Yyg.js) : elle change dès que le contenu change, ce qui permet de mettre ces fichiers en cache pour un an sans risque de servir une ancienne version.

Les 360 ko de JavaScript (112 ko compressés) sont surtout React et les bibliothèques : c'est le coût de départ d'une SPA, à surveiller. Pour tester le résultat avant de le publier :

npm run preview    # sert dist/ sur http://localhost:4173

Les variables d'environnement

L'adresse de l'API, le nom de l'environnement ou une clé publique de service changent entre le développement et la production. Vite lit des fichiers .env à la racine du projet :

# .env.production
VITE_API_URL=/v1
VITE_NOM_ENVIRONNEMENT=production

Dans le code, on les lit avec import.meta.env :

const BASE = import.meta.env.VITE_API_URL ?? '/v1';

if (import.meta.env.DEV) console.log('Mode développement');

Pour que TypeScript connaisse tes variables, crée le fichier src/vite-env.d.ts (le modèle n'en fournit plus) :

interface ImportMetaEnv {
  readonly VITE_API_URL?: string;
}

Deuxième conséquence : les valeurs sont figées au moment du build. Changer .env.production sur le serveur après coup ne change rien ; il faut reconstruire. C'est pour cela qu'une adresse d'API relative (/v1) est pratique : le même build fonctionne sur tous les serveurs qui relaient /v1 vers l'API.

Le problème des adresses profondes

Ton application est en ligne. La page d'accueil marche, tu cliques sur une fiche, l'adresse devient https://frais.gsb.example/fiches/12. Tu appuies sur F5… 404 Not Found.

Pourquoi : en cliquant, c'est React Router qui a changé l'adresse, dans le navigateur, sans requête. En rechargeant, le navigateur demande vraiment /fiches/12 au serveur, qui cherche un fichier fiches/12 dans dist/ et ne le trouve pas. Le serveur doit renvoyer index.html pour toute adresse qui ne correspond pas à un fichier : React se charge, React Router lit l'adresse et affiche la fiche. C'est la redirection de repli (SPA fallback), à configurer sur chaque hébergement.

Servir le front et l'API sur le même domaine

La configuration recommandée pour AppliFrais reproduit en production le proxy de Vite : un serveur web (Nginx, Apache, Caddy) sert les fichiers de dist/ et relaie /v1/ vers l'API Node.js. Le navigateur ne voit qu'une origine : pas de CORS, et pas de requête de pré-vérification OPTIONS avant chaque appel qui porte l'en-tête Authorization (chapitre 12).

Avec Nginx :

server {
    listen 80;
    server_name frais.gsb.example;
    root /var/www/appli-frais/dist;
    index index.html;

    # L'API : ses routes commencent par /v1, relayées au serveur Node.js
    location /v1/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Les fichiers avec empreinte : en cache pour un an
    location /assets/ {
        add_header Cache-Control "public, max-age=31536000, immutable";
        try_files $uri =404;
    }

    # Tout le reste : le fichier s'il existe, sinon index.html (le routeur prend le relais)
    location / {
        add_header Cache-Control "no-cache";
        try_files $uri $uri/ /index.html;
    }
}

• try_files $uri $uri/ /index.html : c'est la redirection de repli.
• index.html est servi avec no-cache (le navigateur revérifie à chaque visite) : après un nouveau déploiement, il charge la nouvelle page, qui pointe vers les nouveaux fichiers à empreinte.
• proxy_pass http://127.0.0.1:3000 sans chemin à la fin transmet l'adresse complète (/v1/fiches) à l'API. Derrière ce proxy, l'API active trust proxy (cours Node.js).
• En production, ce serveur écoute en HTTPS (port 443) avec un certificat, par exemple de Let's Encrypt ; le port 80 ne sert qu'à rediriger vers HTTPS. Le jeton d'accès ne doit jamais circuler en clair : intercepté, il ouvrirait le compte jusqu'à son expiration.

Avec Apache, la redirection de repli tient en une ligne dans un fichier .htaccess placé dans dist/ (ou dans la configuration du site) : FallbackResource /index.html.

Les hébergeurs statiques

Si l'API est hébergée ailleurs, le front seul peut aller sur un hébergeur de sites statiques, souvent gratuit pour un projet personnel. Chacun a sa façon de déclarer la redirection de repli :

Dans ce cas, l'API est sur une autre origine : elle doit autoriser celle du front avec CORS (la variable CORS_ORIGIN de l'API du cours Node.js), et le front doit fixer VITE_API_URL à l'adresse complète de l'API, par exemple https://api.gsb.example/v1 pour l'API déployée dans le cours Node.js. Comme le jeton voyage dans un en-tête et non dans un cookie, il n'y a rien d'autre à régler (CORS).

Déployer avec Docker

Pour livrer le front comme une image (le cours Docker explique les images et les conteneurs), on utilise une construction en plusieurs étapes : une image Node.js construit l'application, une image Nginx ne garde que le résultat.

# Étape 1 : construire
FROM node:24-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

# Étape 2 : servir les fichiers statiques
FROM nginx:stable-alpine
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /app/dist /usr/share/nginx/html

Le fichier nginx.conf reprend la configuration ci-dessus, avec root /usr/share/nginx/html et proxy_pass http://api:3000, où api est le nom du service de l'API dans le fichier compose.yaml. L'image finale ne contient ni Node.js, ni node_modules, ni le code source : quelques dizaines de mégaoctets. Pense à un fichier .dockerignore qui exclut node_modules et dist.

Vérifier avant chaque déploiement : l'intégration continue

Un déploiement ne devrait jamais partir avec un test qui échoue ou une erreur de types. Une chaîne d'intégration continue le garantit : à chaque git push, elle installe les dépendances, lance le linter, les tests et le build (cours CI/CD).

# .github/workflows/front.yml
name: Front AppliFrais
on: [push, pull_request]

jobs:
  verifier:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npx vitest run
      - run: npm run build
      - uses: actions/upload-artifact@v7
        with:
          name: dist
          path: dist

npm ci installe exactement les versions du package-lock.json. L'artefact dist est le paquet prêt à déployer : l'étape de déploiement continu le récupère et le publie.

Les derniers réglages de production

Exercices

# .env.production
VITE_API_URL=https://api.gsb.example/v1

# public/_redirects (copié dans dist/ au build)
/*  /index.html  200