---
title: Remplacer webpack par vite.js
slug: oip-next/v3/migration/viteJS
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-13T08:55:17.000Z
---

# 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 ](https://vite.dev/config/)

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).&#x20;
- Commande de **build** préconfigurée pour générer des assets statiques optimisés.&#x20;

### Gains observés par rapport à un setup Webpack

- Configuration **plus simple** grâce à de nombreuses fonctionnalités intégrées.&#x20;
- **Un seul fichier** de configuration: `vite.config.js` couvre développement et production.&#x20;
- Très peu de **dépendances** additionnelles (moins de 5 en général, contre une vingtaine côté Webpack).&#x20;
- **Performances** supérieures: démarrage du serveur, HMR et build plus rapides.&#x20;

**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`:

:::CodeblockTabs
package.json

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

Utilisez ensuite **exclusivement&#x20;**&#x6C;a syntaxe **ESM&#x20;**&#x63;ôté client:

```javascript
// 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**:

```javascript
// 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`.&#x20;

Renommez les fichiers contenant du JSX en `.jsx`pour 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:

:::CodeblockTabs
to remove

```none
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 :

:::CodeblockTabs
to update

```none
babel-plugin-relay@18.2.0
react-relay@18.2.0
relay-compiler@18.2.0
relay-runtime@18.2.0
```
:::

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

:::CodeblockTabs
relay.config.json

```json
{
  "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` :

:::CodeblockTabs
package.json

```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:

- vite\@6.1.1
- @vitejs/plugin-react-swc\@3.8.0
- vite-plugin-relay\@2.1.0

## Point d'entrée

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

:::CodeblockTabs
index.html

```html
<!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:

:::CodeblockTabs
vite.config.js

```javascript
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&#x20;**`public`**)**

### Éléments à migrer depuis Webpack

Selon votre projet, pensez à migrer:

- **Variables d’environnement** utilisées par le client.&#x20;
- **Alias d’import**.&#x20;
- **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`.
&#x20;Avec Vite, chargez-les via `loadEnv` et exposez celles qui doivent être accessibles au code client via `define`:

:::CodeblockTabs
vite.config.js

```javascript
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.&#x20;
- 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`:

:::CodeblockTabs
vite.config.js

```javascript
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&#x20;

`resolve.alias`:

:::CodeblockTabs
vite.config.js

```javascript
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
      ]
    }
  };
});
```

vite-view-aliases.js

```javascript
import fs from 'fs';
import path from 'path';
import * as R from 'ramda';

export const viteViewAliases = (dir, rootDir) => {
  const eachAllFiles = dir =>
    fs.readdirSync(dir).reduce((files, file) => {
      const name = path.join(dir, file);
      const isDirectory = fs.statSync(name).isDirectory();
      return isDirectory ? [...files, name, ...eachAllFiles(name)] : [...files];
    }, []);

  return eachAllFiles(dir).reduce((acc, file) => {
    const [views, name] = R.split(path.sep, file);
    const alias = `@@${views}/${name}`;

    if (!acc.some(entry => entry.find === alias)) {
      acc.push({
        find: alias,
        replacement: path.resolve(rootDir || '/service', `${views}/${name}/client`)
      });
    }

    return acc;
  }, []);
};
```
:::

## Les endpoints API

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

:::CodeblockTabs
vite.config.js

```javascript
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:

:::CodeblockTabs
to remove

```none
.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**.
&#x20;Dans le stage responsable du build du front (celui qui se termine par `RUN yarn front:build`):

- Supprimez les instructions liées à Webpack.&#x20;
- Vérifiez que tous les fichiers nécessaires au build Vite sont copiés dans le `WORKDIR`.

Exemple :

```dockerfile
# ...

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*) :

```shell
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 :

:::CodeblockTabs
.gitignore

```none
# 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:

```shell
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 :

```dockerfile
# ...

# 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.
