· 7 min read
Migrating a React Front End to Vite: A Practical Checklist
- React
- Vite
- TypeScript
- Frontend
- DevOps
Why migrate at all#
At the German Aerospace Center (DLR) I worked on the front end of a simulation platform used for human–machine interaction research, and part of that work was moving it from a Webpack-based React setup to Vite. The motivation is common to many older React projects: slow cold starts, slow hot reloads and a build configuration nobody wants to touch.
Vite serves source files as native ES modules during development and only bundles for production (with Rollup), so the dev server starts almost immediately and updates are near-instant. The migration itself is mostly mechanical, but a handful of details reliably break builds. This is the checklist I now use.
1. Inventory what the old build does#
Before deleting anything, write down every job the current toolchain performs:
- Entry point and HTML template
- Environment variables and how they are injected
- Path aliases (
@/components,~/utils) - Loaders: SVG as components, CSS modules, Sass, images, web workers
- Dev-server proxy rules to backend APIs
- Test runner configuration (Jest transforms, mocks)
Each item maps to a Vite feature or plugin. Anything you forget here shows up later as a confusing runtime error.
2. Install Vite and move index.html#
npm install --save-dev vite @vitejs/plugin-react
Vite treats index.html as the entry point, so it lives in the project root and references your entry module directly:
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
Remove %PUBLIC_URL% placeholders; files in public/ are served from /.
3. A minimal vite.config.ts#
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'node:path';
export default defineConfig({
plugins: [react()],
resolve: {
alias: { '@': path.resolve(__dirname, 'src') },
},
server: {
port: 3000,
proxy: { '/api': 'http://localhost:8080' },
},
build: { sourcemap: true },
});
Keep the TypeScript paths in tsconfig.json in sync with resolve.alias, or your editor and your build will disagree.
4. Environment variables#
This is the most common breakage. Vite does not provide process.env in the browser. Variables must be prefixed with VITE_ and are read from import.meta.env:
// before
const api = process.env.REACT_APP_API_URL;
// after
const api = import.meta.env.VITE_API_URL;
Add a type declaration so TypeScript knows about them:
/// <reference types="vite/client" />
interface ImportMetaEnv {
readonly VITE_API_URL: string;
}
Remember that anything prefixed VITE_ ends up in the client bundle. Secrets never belong there.
5. Assets, SVGs and CSS#
- Plain image imports work out of the box.
- SVGs imported as React components need
vite-plugin-svgr, and the import becomesimport Logo from './logo.svg?react'. - CSS modules work if files are named
*.module.css. - Sass needs only
npm i -D sass.
6. Tests: Jest to Vitest#
Vitest reuses the Vite config, so aliases and transforms match production:
// vite.config.ts
test: {
environment: 'jsdom',
setupFiles: './src/setupTests.ts',
globals: true,
},
Most Jest tests run unchanged; jest.fn() becomes vi.fn(), and module mocks move to vi.mock().
7. Gotchas I would check first#
| Symptom | Usual cause |
|---|---|
process is not defined |
A dependency or your code still reads process.env |
| Blank page in production only | Wrong base when the app is served from a sub-path |
require is not defined |
CommonJS-only code imported from an ES module |
| Works in dev, fails in build | Case-sensitive import paths on Linux CI runners |
| Large first load | Dynamic imports were not preserved; check build.rollupOptions |
8. Roll it out safely#
- Run old and new builds side by side in CI for a while and compare bundle output.
- Deploy behind the same URL to a staging environment and click through critical paths.
- Remove Webpack, Babel and Jest configs only after the Vite build has shipped.
Takeaways#
A Vite migration is low-risk when you treat it as an inventory exercise: list every job the old toolchain performs, map each to its Vite equivalent, and verify environment variables, assets and tests explicitly. The payoff is a much faster feedback loop for everyone who works on the front end.