Construire des apps React 10x plus vite avec Rspack et Rsbuild : le guide complet du bundler Rust

Si vous avez déjà attendu des minutes pour que votre build webpack se termine, vous connaissez cette douleur. Rspack et Rsbuild sont là pour changer la donne. Écrit en Rust, Rspack est un remplacement direct de webpack qui offre des vitesses de build jusqu'à 10 fois plus rapides, tandis que Rsbuild est l'outil de build haut niveau qui fournit une expérience de développement prête à l'emploi.

Dans ce tutoriel, vous allez construire une application React complète depuis zéro avec Rsbuild, puis apprendre à configurer Rspack directement pour les cas avancés. Vous apprendrez également à migrer un projet webpack existant étape par étape.

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Node.js 18+ installé (Node 20 recommandé)
• npm, yarn ou pnpm comme gestionnaire de paquets
• Des connaissances de base en React et TypeScript
• Un éditeur de code (VS Code recommandé)
• Optionnel : un projet webpack existant si vous prévoyez de migrer

Ce que vous allez construire

À la fin de ce tutoriel, vous aurez :

1. Une nouvelle application React + TypeScript construite avec Rsbuild depuis zéro
2. Une compréhension de la configuration Rspack pour un contrôle avancé
3. Les connaissances pour migrer tout projet webpack vers Rspack

Comprendre l'écosystème Rspack

Avant de plonger dans le code, comprenons les deux outils principaux :

• Rspack est le bundler bas niveau, un remplacement de webpack écrit en Rust. Il est compatible avec la plupart des plugins et loaders webpack tout en étant considérablement plus rapide.
• Rsbuild est l'outil de build haut niveau construit sur Rspack. Pensez-y comme ce que Create React App ou Vite est pour leurs bundlers respectifs, mais propulsé par Rspack.

Quand utiliser lequel ?

Étape 1 : Créer un nouveau projet React avec Rsbuild

La façon la plus rapide de commencer est d'utiliser le générateur de projets Rsbuild :

npm create rsbuild@latest

Quand on vous le demande, sélectionnez :

• Nom du projet : my-rsbuild-app
• Framework : React
• Langage : TypeScript

Cela crée un projet avec des paramètres par défaut intelligents. Naviguez dedans et installez les dépendances :

cd my-rsbuild-app
npm install

Lancez le serveur de développement :

npm run dev

Votre application devrait tourner sur http://localhost:3000 avec un Hot Module Replacement (HMR) ultra-rapide.

Étape 2 : Explorer la structure du projet

Le projet généré a une structure propre :

my-rsbuild-app/
  src/
    App.tsx
    App.css
    index.tsx
    env.d.ts
  rsbuild.config.ts
  tsconfig.json
  package.json

Le fichier clé est rsbuild.config.ts. Ouvrez-le :

import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
 
export default defineConfig({
  plugins: [pluginReact()],
});

C'est tout. Deux lignes de configuration et vous avez un setup React + TypeScript complet avec :

• Compilation basée sur SWC (pas besoin de Babel)
• Support des CSS Modules
• Fast Refresh (HMR)
• Code splitting automatique
• Chargement des variables d'environnement

Étape 3 : Configurer Rsbuild pour la production

Ajoutons une configuration prête pour la production. Mettez à jour rsbuild.config.ts :

import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
 
export default defineConfig({
  plugins: [
    pluginReact({
      swcReactOptions: {
        runtime: 'automatic',
      },
      splitChunks: {
        react: true,
        router: true,
      },
    }),
  ],
  source: {
    entry: {
      index: './src/index.tsx',
    },
  },
  output: {
    distPath: {
      root: 'dist',
    },
    cleanDistPath: true,
    sourceMap: {
      js: process.env.NODE_ENV === 'production'
        ? 'source-map'
        : 'cheap-module-source-map',
    },
  },
  html: {
    title: 'My Rsbuild App',
    favicon: './src/favicon.ico',
  },
  server: {
    port: 3000,
    open: true,
  },
  performance: {
    chunkSplit: {
      strategy: 'split-by-experience',
    },
  },
});

Ce que fait chaque section :

• plugins : Enregistre le plugin React avec le splitting des chunks pour React et React Router
• source.entry : Définit le point d'entrée de l'application
• output : Configure la sortie du build, les source maps et le nettoyage
• html : Définit le titre de la page et le favicon
• server : Configuration du serveur de développement avec ouverture automatique
• performance.chunkSplit : Divise intelligemment les chunks vendors selon les patterns courants

Étape 4 : Ajouter les CSS Modules et le styling

Rsbuild supporte les CSS Modules nativement. Créez un composant avec des styles scopés :

/* src/components/Card.module.css */
.card {
  border: 1px solid #e0e0e0;
  border-radius: 12px;
  padding: 24px;
  transition: box-shadow 0.2s ease;
}
 
.card:hover {
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}
 
.title {
  font-size: 1.25rem;
  font-weight: 600;
  margin-bottom: 8px;
}
 
.description {
  color: #666;
  line-height: 1.6;
}

// src/components/Card.tsx
import styles from './Card.module.css';
 
interface CardProps {
  title: string;
  description: string;
}
 
export function Card({ title, description }: CardProps) {
  return (
    <div className={styles.card}>
      <h3 className={styles.title}>{title}</h3>
      <p className={styles.description}>{description}</p>
    </div>
  );
}

Tout fichier se terminant par .module.css est automatiquement traité comme un CSS Module. Aucune configuration nécessaire.

Étape 5 : Variables d'environnement

Rsbuild charge automatiquement les fichiers .env. Créez un fichier .env :

# .env
PUBLIC_API_URL=https://api.example.com
PUBLIC_APP_NAME=My Rsbuild App

Accédez-y dans votre code :

// Les variables préfixées par PUBLIC_ sont disponibles dans le code client
console.log(process.env.PUBLIC_API_URL);
console.log(process.env.PUBLIC_APP_NAME);

Vous pouvez personnaliser le préfixe dans votre configuration :

export default defineConfig({
  loadEnv: {
    prefixes: ['PUBLIC_', 'REACT_APP_'],
  },
});

C'est particulièrement utile lors de la migration depuis Create React App, où les variables utilisent le préfixe REACT_APP_.

Étape 6 : Configuration avancée de Rspack

Pour les projets nécessitant un contrôle au niveau webpack, vous pouvez utiliser Rspack directement. Voici un rspack.config.ts complet pour un projet React + TypeScript :

import { defineConfig } from '@rspack/cli';
import { rspack, type SwcLoaderOptions } from '@rspack/core';
import { ReactRefreshRspackPlugin } from '@rspack/plugin-react-refresh';
 
const isDev = process.env.NODE_ENV === 'development';
const targets = ['last 2 versions', '> 0.2%', 'not dead'];
 
export default defineConfig({
  entry: {
    main: './src/index.tsx',
  },
  output: {
    path: './dist',
    filename: isDev ? '[name].js' : '[name].[contenthash:8].js',
    cssFilename: isDev ? '[name].css' : '[name].[contenthash:8].css',
    clean: true,
  },
  resolve: {
    extensions: ['.tsx', '.ts', '.jsx', '.js'],
    alias: {
      '@': './src',
    },
  },
  module: {
    rules: [
      {
        test: /\.(tsx?|jsx?)$/,
        exclude: /node_modules/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'typescript',
                tsx: true,
              },
              transform: {
                react: {
                  runtime: 'automatic',
                  development: isDev,
                  refresh: isDev,
                },
              },
            },
            env: { targets },
          } satisfies SwcLoaderOptions,
        },
      },
      {
        test: /\.css$/,
        type: 'css/auto',
      },
      {
        test: /\.(png|jpe?g|gif|svg|webp)$/,
        type: 'asset',
        parser: {
          dataUrlCondition: {
            maxSize: 8 * 1024, // 8KB
          },
        },
      },
    ],
  },
  plugins: [
    new rspack.HtmlRspackPlugin({
      template: './index.html',
    }),
    new rspack.DefinePlugin({
      'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
    }),
    isDev && new ReactRefreshRspackPlugin(),
  ].filter(Boolean),
  devServer: {
    port: 3000,
    hot: true,
    historyApiFallback: true,
  },
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendor',
          chunks: 'all',
        },
      },
    },
  },
});

Différences clés avec webpack :

1. builtin:swc-loader remplace complètement babel-loader. Écrit en Rust, il compile TypeScript et JSX nativement.
2. Le type css/auto gère les fichiers CSS, y compris la détection automatique des CSS Modules.
3. rspack.HtmlRspackPlugin est un remplacement natif Rust de html-webpack-plugin.
4. ReactRefreshRspackPlugin remplace @pmmmwh/react-refresh-webpack-plugin.

Étape 7 : Migrer un projet Webpack existant

Si vous avez un projet webpack existant, suivez ces étapes :

7.1 : Installer Rspack

npm install @rspack/core @rspack/cli -D
npm install @rspack/plugin-react-refresh -D

7.2 : Renommer la configuration

mv webpack.config.js rspack.config.js

7.3 : Mettre à jour les scripts

{
  "scripts": {
    "dev": "rspack serve",
    "build": "rspack build"
  }
}

7.4 : Remplacer babel-loader par builtin:swc-loader

Supprimez les dépendances Babel :

npm uninstall babel-loader @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript

Remplacez la règle babel-loader dans votre configuration :

// Avant (webpack)
{
  test: /\.(js|jsx|ts|tsx)$/,
  exclude: /node_modules/,
  use: {
    loader: 'babel-loader',
    options: {
      presets: [
        '@babel/preset-env',
        '@babel/preset-react',
        '@babel/preset-typescript',
      ],
    },
  },
}
 
// Après (rspack)
{
  test: /\.(js|jsx|ts|tsx)$/,
  exclude: /node_modules/,
  use: {
    loader: 'builtin:swc-loader',
    options: {
      jsc: {
        parser: {
          syntax: 'typescript',
          tsx: true,
        },
        transform: {
          react: {
            runtime: 'automatic',
            development: process.env.NODE_ENV === 'development',
            refresh: process.env.NODE_ENV === 'development',
          },
        },
      },
    },
  },
}

7.5 : Remplacer les plugins

7.6 : Gérer le CSS

Remplacez la chaîne css-loader + style-loader par le type CSS intégré :

// Avant (webpack)
{
  test: /\.css$/,
  use: ['style-loader', 'css-loader'],
}
 
// Après (rspack)
{
  test: /\.css$/,
  type: 'css/auto',
}

Étape 8 : Ajouter des plugins populaires

Support Sass/SCSS

npm install @rsbuild/plugin-sass -D

import { pluginSass } from '@rsbuild/plugin-sass';
 
export default defineConfig({
  plugins: [
    pluginReact(),
    pluginSass(),
  ],
});

SVG comme composants React

npm install @rsbuild/plugin-svgr -D

import { pluginSvgr } from '@rsbuild/plugin-svgr';
 
export default defineConfig({
  plugins: [
    pluginReact(),
    pluginSvgr({
      svgrOptions: {
        exportType: 'named',
      },
    }),
  ],
});

Utilisez les SVG comme composants :

import { ReactComponent as Logo } from './logo.svg';
 
function App() {
  return <Logo width={100} height={100} />;
}

Tailwind CSS

Pas besoin de plugin spécial. Installez simplement Tailwind et configurez-le normalement :

npm install tailwindcss @tailwindcss/postcss postcss -D

Créez postcss.config.js :

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

Puis importez Tailwind dans votre CSS :

@import "tailwindcss";

Rsbuild détecte automatiquement la configuration PostCSS.

Étape 9 : Build et analyse

Lancez le build de production :

npm run build

Vous remarquerez que le build se termine nettement plus vite que webpack. Pour un projet React de taille moyenne, attendez-vous à :

Pour analyser votre bundle :

RSBUILD_BUNDLE_ANALYZE=true npm run build

Cela génère un rapport d'analyse interactif du bundle dans votre navigateur.

Tester votre implémentation

Vérifiez que tout fonctionne correctement :

1. Serveur de développement : Lancez npm run dev et confirmez que le HMR fonctionne en modifiant un composant
2. CSS Modules : Vérifiez que les styles sont scopés (les noms de classes doivent être hashés)
3. TypeScript : Introduisez une erreur de type et vérifiez qu'elle apparaît dans le terminal
4. Build de production : Lancez npm run build et servez le dossier dist
5. Variables d'environnement : Ajoutez une variable PUBLIC_ et loggez-la dans un composant

Dépannage

Erreur "Module not found" pour les loaders webpack

Si vous voyez des erreurs concernant des loaders manquants, vous utilisez probablement un loader spécifique à webpack. Vérifiez si Rspack a un remplacement intégré (la plupart des loaders courants en ont un).

CSS non extrait en production

Assurez-vous d'utiliser type: 'css/auto' dans vos règles Rspack. Rsbuild gère cela automatiquement.

React Fast Refresh ne fonctionne pas

Assurez-vous que ReactRefreshRspackPlugin est ajouté uniquement en mode développement et que refresh: true est défini dans vos options SWC.

Plugins webpack non compatibles

Bien que la plupart des plugins webpack fonctionnent, certains qui dépendent d'API internes de webpack peuvent ne pas fonctionner. Consultez la liste de compatibilité sur rspack.dev pour des alternatives.

Prochaines étapes

• Explorez l'écosystème complet des plugins Rsbuild sur rsbuild.dev
• Configurez Storybook avec Rsbuild en utilisant storybook-rsbuild
• Essayez Module Federation pour les micro-frontends avec Rspack
• Ajoutez les tests avec Vitest (fonctionne parfaitement avec Rsbuild)
• Découvrez Rslib pour construire des packages de bibliothèques avec Rspack

Conclusion

Rspack et Rsbuild apportent la vitesse de Rust au monde du bundling JavaScript sans sacrifier la compatibilité avec webpack. Que vous commenciez un nouveau projet avec l'approche zéro-configuration de Rsbuild ou que vous migriez un projet webpack existant vers Rspack, vous obtiendrez des améliorations spectaculaires de la vitesse de build avec un effort minimal.

Le point clé à retenir : commencez avec Rsbuild pour les nouveaux projets (il gère la complexité pour vous), et utilisez Rspack directement quand vous avez besoin d'un contrôle fin au niveau webpack. Dans les deux cas, vos builds seront plus rapides, votre expérience de développement plus fluide, et votre équipe plus heureuse.