Remplacer webpack par vite.js

23 min

Migration Webpack vers Vite pour une application React

Cette documentation a pour objectif de vous guider dans le remplacement de Webpack par Vite comme outil de build de votre application React.

⚠️ Ce guide s'applique uniquement aux projets initiés avec un OIP Starter v2.

Documentation Vite : vite.dev

Exemple interne : POC réalisé sur le projet d'un client. Adaptez les étapes à votre contexte si nécessaire.

L’équipe OIP reste disponible pour toute question relative à ce guide. Contactez-nous en cas de difficulté ou pour nous transmettre vos retours.

Pourquoi Vite

Vite est un outil de build moderne pour les projets web. Il est rapide, léger et simple à configurer.

Fonctionnalités principales

Serveur de développement avec HMR (Hot Module Replacement).

Commande de build préconfigurée pour générer des assets statiques optimisés.

Gains observés par rapport à un setup Webpack

Configuration plus simple grâce à de nombreuses fonctionnalités intégrées.

Un seul fichier de configuration: vite.config.js couvre développement et production.

Très peu de dépendances additionnelles (moins de 5 en général, contre une vingtaine côté Webpack).

Performances supérieures: démarrage du serveur, HMR et build plus rapides.

En résumé, le passage à Vite simplifie la configuration, allège votre codebase et améliore la maintenabilité. Vous gagnez aussi en rapidité et en confort lors du dev et du build.

Préparation à l'installation de vite

Activer les modules ES

Pour éviter d’ajouter des loaders personnalisés, activez les modules ES dans package.json:

{
  "name": "my-oav",
  "type": "module", // enable ES6 module
  ...
}

Utilisez ensuite exclusivement la syntaxe ESM côté client:

// before
const R = require('ramda');

// now
import * as R from 'ramda';

Cela vaut aussi pour tous les fichiers de configuration client, comme par exemple les fichiers de configuration liés à tailwind :

tailwind.config.js

postcss.config.js

Faites la même chose pour les fichiers de configuration client, par exemple Tailwind:

// before
module.exports = {
  // ... config
}

// now
export default {
  // ... config
}

JSX dans les fichiers JS

Par défaut, Vite n’apprécie pas le JSX dans des fichiers .js.

Renommez les fichiers contenant du JSX en .jsxpour ne pas alourdir la config.

Supprimer les dépendances Webpack et Babel

Retirez du package.json les dépendances liées à Webpack et Babel. Liste non exhaustive:

dotenv-webpack
@pmmmwh/react-refresh-webpack-plugin
clean-webpack-plugin
copy-webpack-plugin
html-webpack-plugin
html-webpack-template
webpack
webpack-cli
webpack-dev-server
webpack-merge
mini-css-extract-plugin
react-hot-loader
@babel/core
@babel/polyfill
@babel/preset-env
@babel/preset-react
@babel/register
@babel/runtime
@loadable/babel-plugin
babel-jest
babel-loader
node-loader
file-loader
postcss-loader
style-loader

Mise à jour de Relay

Pour une meilleure compatibilité avec Vite, mettez à jour Relay.

Retour d’expérience : Sur le POC Client, passage de Relay 12.0.0 à 18.2.0 sans erreur ni modification du setup Relay dans la codebase. Votre contexte peut toutefois différer.

Dépendances à mettre à jour :

[email protected]
[email protected]
[email protected]
[email protected]

À la suite de la mise à jour de ces dépendances, créez le fichier de configuration relay.config.json à la racine du projet :

{
  "src": ".",
  "schema": "./schema.graphql",
  "language": "javascript",
  "eagerEsModules": true,
  "exclude": ["**/node_modules/**", "**/__mocks__/**", "**/__generated__/**"]
}

Le fichier relay.config.json remplace les options à passer à la commande relay du package.json

Pour finir, veuillez mettre à jour la commande relay (commande responsable de générer les fichiers relay) dans le package.json :

{
  "name": "my-oav",
  "type": "module",
  "scripts": {
    "relay": "relay-compiler",
    "front:dev": "vite",
    "front:build": "vite build",
    ...
  }
}

Installation de vite

Installez les dépendances de développement suivantes:

[email protected]

@vitejs/[email protected]

[email protected]

Point d'entrée

vite nécessite comme point d'entrée de votre application un fichier index.html à la racine de votre projet :

<!doctype html>
<html lang="fr-FR">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>MY OAV</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/app/index.jsx"></script>
  </body>
</html>

Veuillez vous assurer que la balise <script type="module" src="..."> fait bien référence à l'index du code source de votre application React.

Fichier de configuration Vite

Créez vite.config.js à la racine du projet.

Template de base adapté aux projets Fasst:

import react from '@vitejs/plugin-react-swc';
import relay from 'vite-plugin-relay';
import path, { dirname } from 'path';
import { fileURLToPath } from 'url';
import { defineConfig, loadEnv } from 'vite';

const __dirname = dirname(fileURLToPath(import.meta.url));

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '');

  return {
    build: {
      outDir: path.resolve(__dirname, 'dist'),
      sourcemap: mode === 'development'
    },
    define: {
      'process.env.API_KEY': JSON.stringify(env.API_KEY),
      'process.env.API_USER_ID': JSON.stringify(env.API_USER_ID)
    },
    plugins: [relay, react()],
    resolve: {
      alias: [
        { find: '@@app', replacement: path.resolve(__dirname, 'app') },
        // ... others alias
      ]
    },
    server: {
      port: 8000,
      proxy: {
        '/api': {
          target: `http://localhost:${env.PORT}`,
          changeOrigin: true
        },
        // ... others REST enpoints
      }
    }
  };
});

Astuce: Le port du server de dev peut être changé via la propriété server.port de la config vite.

Par défaut vite gère de nombreuses features out of the box comme le chargement des fichiers CSS ou des fichiers statiques (dossier public)

Éléments à migrer depuis Webpack

Selon votre projet, pensez à migrer:

Variables d’environnement utilisées par le client.

Alias d’import.

Endpoints API du serveur de dev.

Variables d’environnement

Dans la configuration Webpack, les variables étaient définies dans .env.dev.webpack et .env.prod.webpack. Avec Vite, chargez-les via loadEnv et exposez celles qui doivent être accessibles au code client via define:

import { defineConfig, loadEnv } from 'vite';

export default defineConfig(({ mode }) => {
  // chargement de l'env
  const env = loadEnv(mode, process.cwd(), '');

  return {
    define: {
      // process.env.MY_VAR sera accessible depuis le code source client
      'process.env.MY_VAR': JSON.stringify(env.MY_VAR),
    },
  };
});

Organisation recommandée des fichiers d’environnement

Créez .env.prod pour les variables utilisées lors du build Docker en production.

Placez les variables de développement côté client dans .env et .env.dist.

Alias d’import

Les alias définis dans webpack.common.js doivent être déplacés dans vite.config.js:

import { fileURLToPath } from 'url';

const __dirname = dirname(fileURLToPath(import.meta.url));

export default defineConfig(({ mode }) => {
  // ...

  return {
    resolve: {
      alias: [
        {
          find: '@@myAlias',
          replacement: path.resolve(__dirname, 'path/to/dir') 
        },
      ]
    }
  };
});

Pour gérer un grand nombre d’alias de vues, créez un module utilitaire qui les résout, puis étendez

resolve.alias:

import { fileURLToPath } from 'url';
import { viteViewAliases } from './vite-view-aliases.js';

const __dirname = dirname(fileURLToPath(import.meta.url));

export default defineConfig(({ mode }) => {
  // ...

  return {
    resolve: {
      alias: [
        { find: '@@myAlias', replacement: path.resolve(__dirname, 'path/to/dir') },
        ...viteViewAliases('views', env.ROOT_DIR), // view aliases
      ]
    }
  };
});

Les endpoints API

Les proxys définis dans webpack.dev.js doivent être migrés vers server.proxy:

import { defineConfig, loadEnv } from 'vite';

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '');

  return {
    // ...
    server: {
      proxy: {
        '/api': {
          target: `http://localhost:${env.PORT}`,
          changeOrigin: true
        },
        // ... others REST enpoints
      }
    }
  };
});

Nettoyage des fichiers Webpack

Supprimez les fichiers de configuration obsolètes:

.babelrc
.env.dev.webpack
.env.prod.webpack
webpack.common.js
webpack.dev.js
webpack.prod.js
webpackViewsAlias.js

Dockerfile

Une fois Vite installé et configuré, mettez à jour votre Dockerfile. Dans le stage responsable du build du front (celui qui se termine par RUN yarn front:build):

Supprimez les instructions liées à Webpack.

Vérifiez que tous les fichiers nécessaires au build Vite sont copiés dans le WORKDIR.

Exemple :

# ...

FROM base AS client
WORKDIR /service

ARG NPM_TOKEN=${NPM_TOKEN}

# vite files
COPY index.html vite.config.js vite-view-aliases.js ./

# tailwind files
COPY postcss.config.js tailwind.config.js ./

# relay files
COPY relay.config.json schema.graphql ./

# env
COPY .env.prod .env

# sources
COPY app ./app
COPY views ./views
COPY public ./public

# install
RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" >> .npmrc \
  && yarn install \
  && rm .npmrc

# build frontend sources
RUN yarn front:build

# ...

Pour tester le build de l'image, vous pouvez exécuter la commande suivante par exemple (arguments à adapter selon votre Dockerfile) :

docker buildx build --build-arg NPM_TOKEN=my-token -t my-oav:latest --no-cache .

Git: ignorer les fichiers générés par Relay

Étape optionnelle mais recommandée pour réduire la taille du dépôt.

relay-compiler génère un fichier par requête ou mutation GraphQL. Ils sont nécessaires au build et à l’exécution, mais n’ont pas besoin d’être versionnés.

Pour ignorer les fichiers relay, veuillez ajouter au fichier .gitignore les entrés suivantes :

# ignore all __generated__ dirs from app and views
app/**/__generated__
views/**/__generated__

# do not ignore, file generated by OIP Tools
!views/__generated__

Retirer les fichiers déjà indexés:

git rm -r --cached app/**/__generated__ views/**/__generated__

Ensuite éditer le fichier Dockerfile et ajouter la commande relay avant la commande front:build dans le stage du build de l'application client :

# ...

# run relay-compiler to generate gql files
RUN yarn relay

# build frontend source
RUN yarn front:build

Pensez à committer les changements. Après un clone, exécutez yarn relay et yarn front:build avant de lancer l’application.