Create React App zu Vite migrieren: Schritt fuer Schritt

1. Warum Create React App zu Vite migrieren jetzt notwendig ist

Create React App wurde offiziell archiviert, bekommt keine Updates fuer neue React Versionen mehr und wird von der React Dokumentation nicht mehr empfohlen. Wer eine bestehende Anwendung betreibt, muss frueher oder spaeter Create React App zu Vite migrieren, weil react-scripts intern auf veralteten Versionen von Webpack, Babel und ESLint aufbaut, die Sicherheitsluecken anhaeufen und irgendwann nicht mehr gewartet werden.

Der zweite Treiber ist die Entwicklererfahrung. Der Dev Server von Create React App braucht bei mittelgrossen Projekten oft mehrere Sekunden fuer den initialen Start und spuerbare Verzoegerungen bei Hot Module Replacement. Vite nutzt native ES Module im Browser waehrend der Entwicklung und startet dadurch in der Regel unter einer Sekunde, was bei jedem Speichern direkt spuerbar wird.

Der dritte Grund: viele moderne Bibliotheken testen und dokumentieren ihre Setup Anleitungen inzwischen ausschliesslich fuer Vite, waehrend Create React App Setups oft nur noch als Community Workaround existieren. Wer Create React App zu Vite migriert, bekommt damit auch wieder Zugriff auf aktuelle Dokumentation und Community Support fuer neue Tools.

2. Vorbereitung: Abhaengigkeiten und Grundgeruest

Vor der eigentlichen Migration lohnt sich eine Bestandsaufnahme aller react-scripts spezifischen Funktionen im Projekt: Umgebungsvariablen mit dem Praefix REACT_APP_, Proxy Konfiguration in der package.json, sowie CRACO oder react-app-rewired Overrides, falls das Projekt die Webpack Konfiguration bereits angepasst hat. Diese Liste bestimmt den tatsaechlichen Migrationsaufwand deutlich staerker als die reine Projektgroesse.

Danach wird Vite parallel zu react-scripts installiert, sodass beide Toolchains fuer eine Uebergangszeit im selben Repository existieren koennen. Das erlaubt, den neuen Dev Server zu testen, waehrend der bestehende Build weiterhin funktioniert, bis die Migration vollstaendig abgeschlossen ist.

# Install Vite and the React plugin alongside the existing CRA toolchain
npm install --save-dev vite @vitejs/plugin-react

# Vitest replaces Jest as the test runner in a later step
npm install --save-dev vitest @vitest/ui jsdom

# react-scripts, react-app-rewired or craco can be removed once
# vite.config.ts fully replaces their functionality
npm uninstall react-scripts

3. vite.config.ts statt react-scripts

Der Kern der Migration ist die neue vite.config.ts, die alles ersetzt, was zuvor implizit in react-scripts versteckt war. Waehrend Create React App keine sichtbare Konfigurationsdatei hatte, macht Vite jede Einstellung explizit, was zunaechst mehr Code bedeutet, aber langfristig deutlich einfacher zu debuggen ist, weil nichts mehr in einer Blackbox verborgen liegt.

// vite.config.ts: explicit replacement for the hidden react-scripts config
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'node:path';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      // Mirrors a CRA jsconfig.json "baseUrl": "src" setup
      '@': path.resolve(__dirname, './src'),
    },
  },
  server: {
    port: 3000, // Match the old CRA default port for a familiar dev workflow
    open: true,
  },
  build: {
    outDir: 'build', // Keep the output directory CI/CD pipelines already expect
    sourcemap: true,
  },
});

Wer Create React App zu Vite migriert und zuvor CRACO oder react-app-rewired eingesetzt hat, kann alle Overrides in dieser einen Datei zusammenfuehren, statt sie ueber ein separates Overrides Paket zu verwalten. Das reduziert die Anzahl der Build Tool Abhaengigkeiten im Projekt haeufig um zwei bis drei Pakete.

4. Umgebungsvariablen von REACT_APP zu VITE

Create React App erwartet Umgebungsvariablen mit dem Praefix REACT_APP_, zugaenglich ueber process.env.REACT_APP_API_URL. Vite verwendet stattdessen den Praefix VITE_ und stellt die Werte ueber import.meta.env.VITE_API_URL bereit. Diese Umbenennung betrifft jede Stelle im Code, die auf Umgebungsvariablen zugreift, und laesst sich am zuverlaessigsten mit einer projektweiten Suchen und Ersetzen Operation erledigen.

# .env file: rename the prefix from REACT_APP_ to VITE_
# BEFORE (Create React App)
REACT_APP_API_URL=https://api.example.com
REACT_APP_FEATURE_FLAG_NEW_CHECKOUT=true

# AFTER (Vite)
VITE_API_URL=https://api.example.com
VITE_FEATURE_FLAG_NEW_CHECKOUT=true

# Search and replace across the codebase:
grep -rl "process.env.REACT_APP_" src/ \
  | xargs sed -i 's/process\.env\.REACT_APP_/import.meta.env.VITE_/g'

Ein haeufiger Fehler bei dieser Migration: Entwickler vergessen, dass import.meta.env im Gegensatz zu process.env nur zur Build Zeit statisch ersetzt wird und keine dynamischen Schluessel erlaubt. Ein Zugriff wie import.meta.env[dynamicKey] funktioniert nicht zuverlaessig und muss durch explizite, statisch bekannte Variablennamen ersetzt werden.

5. index.html, public Ordner und Assets umziehen

In Create React App liegt die index.html im public Ordner und wird von Webpack als Template behandelt, das Platzhalter wie %PUBLIC_URL% ersetzt. Bei Vite wandert die index.html ins Projekt Root und wird selbst zum Einstiegspunkt des Build Prozesses, inklusive eines direkten <script type="module" src="/src/main.tsx"> Tags statt eines von Webpack injizierten Bundles.

Der public Ordner bleibt bei Vite fuer statische Assets erhalten, die unveraendert kopiert werden sollen, aber %PUBLIC_URL% Platzhalter muessen durch relative Pfade ersetzt werden, weil Vite dieses Webpack spezifische Templating nicht kennt. Bilder und Fonts, die zuvor per import aus src eingebunden wurden, funktionieren bei Vite unveraendert weiter, da beide Tools das ES Module Import System fuer Assets unterstuetzen.

6. Proxy Setup fuer die lokale API Entwicklung

Viele Create React App Projekte nutzen das einfache "proxy": "http://localhost:8080" Feld in der package.json, um API Anfragen waehrend der lokalen Entwicklung an ein Backend weiterzuleiten. Vite bietet dafuer eine deutlich flexiblere, aber auch explizitere Proxy Konfiguration direkt im server Block der vite.config.ts, die pro Pfad Praefix unterschiedliche Ziele erlaubt.

// vite.config.ts: proxy replaces the simple "proxy" field from package.json
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
      },
      '/ws': {
        target: 'ws://localhost:8080',
        ws: true, // WebSocket proxying needs to be enabled explicitly
      },
    },
  },
});

7. Jest zu Vitest migrieren

React Testing Library Tests aendern sich beim Uebertrag von Jest zu Vitest kaum, weil Vitest bewusst eine kompatible API bereitstellt. Die Testfunktionen describe, it und expect bleiben identisch, was die Migration der Tests selbst zur einfachsten Teilaufgabe macht, wenn man Create React App zu Vite migriert. Der aufwendigere Teil liegt in der Jest Konfiguration, die in eine test Sektion der vite.config.ts uebersetzt werden muss.

Mock Funktionen mit jest.mock() werden durch vi.mock() ersetzt, und globale Mock Funktionen wie jest.fn() werden zu vi.fn(). Ein projektweites Suchen und Ersetzen erledigt die meisten dieser Umbenennungen automatisiert, waehrend komplexere Mock Setups mit Modul Hoisting manuelle Anpassung brauchen.

8. Typische Stolpersteine nach der Migration

Der haeufigste Fehler nach der Migration von Create React App zu Vite betrifft absolute Imports, die zuvor ueber jsconfig.json oder tsconfig.json mit baseUrl funktioniert haben. Vite liest diese TypeScript spezifische Konfiguration nicht automatisch fuer die Modulaufloesung zur Laufzeit, weshalb die Alias Konfiguration zusaetzlich in vite.config.ts dupliziert werden muss, wie im Beispiel aus Abschnitt drei gezeigt.

Ein zweiter Stolperstein sind CSS Module und globale Stylesheets, die in seltenen Faellen unterschiedliche Namenskonventionen fuer generierte Klassen zwischen Webpack und Vite erzeugen. Visuelle Regressionstests vor und nach der Migration decken solche Unterschiede zuverlaessig auf, bevor sie in Produktion sichtbar werden.

9. Create React App und Vite im direkten Vergleich

Die folgende Tabelle fasst die konkreten Unterschiede zusammen, die bei der Migration von Create React App zu Vite in der Praxis relevant sind.

Die Tabelle zeigt, dass die Migration von Create React App zu Vite kein reines Performance Upgrade ist, sondern auch die langfristige Wartbarkeit sichert. Ein archiviertes Build Tool ohne Sicherheitsupdates ist fuer produktive Anwendungen ein wachsendes Risiko, das die Migration klar rechtfertigt.

10. Zusammenfassung

Wer Create React App zu Vite migrieren will, sollte mit einem Inventar der react-scripts spezifischen Funktionen beginnen: Umgebungsvariablen, Proxy Konfiguration und eventuelle CRACO Overrides. Die neue vite.config.ts macht alles explizit, was zuvor implizit war, Umgebungsvariablen wandern vom REACT_APP_ zum VITE_ Praefix, und index.html wird selbst zum Einstiegspunkt statt eines Templates im public Ordner.

Proxy Konfiguration, Testumzug von Jest zu Vitest und die Alias Aufloesung fuer absolute Imports sind die Teile, die am meisten Sorgfalt brauchen. Der Lohn der Migration ist ein Dev Server, der in unter einer Sekunde startet, und ein Build Tool, das im Gegensatz zum archivierten Create React App aktiv weiterentwickelt wird und mit neuen React Versionen Schritt haelt.

11. FAQ: Create React App zu Vite migrieren