webpack to Vite skill for Codex

The migration is done when the Vite build serves every route the webpack build did, the same env values reach the app, tests run, the deploy pipeline publishes the new output, and the webpack config is deleted in a separate, reviewable commit. A half-migrated repo with two bundlers and no owner is worse than either.

Before changing anything

1. Read AGENTS.md, package.json scripts, the CI workflow and the deploy config (Dockerfile, Netlify/Vercel settings, nginx) to learn where build/ or dist/ is consumed.
2. Record a baseline with the current build: npm run build, note output size per entry, build time, the env vars it reads, and a list of routes to smoke test.
3. Run the audit script from this skill on the project root:

python3 scripts/audit_webpack_usage.py <project-dir>          # human readable
python3 scripts/audit_webpack_usage.py <project-dir> --json   # for tracking

It reports BLOCK findings (code that will fail under Vite: require(), require.context, module.hot, process.env.REACT_APP_*, JSX in .js, ~ Sass imports, %PUBLIC_URL%, SVG ReactComponent imports, webpack config files) and warn findings (Node built-ins, global, magic comments). Exit code 1 means blocking work remains. Re-run it until it exits 0. 4. Work on a branch. Installing Vite and plugins needs network; in a sandbox without it, ask for approval or have the user run the install.

Migration checklist

• Install: vite, the framework plugin (@vitejs/plugin-react or @vitejs/plugin-vue), vitest, jsdom if tests need it
• Move public/index.html to the project root and add the module entry
• Write vite.config.ts that ports aliases, proxy, defines and output dir
• Convert env access and rename env vars
• Fix every BLOCK finding from the audit
• Port tests from Jest (react-scripts) to Vitest
• Update scripts, CI cache paths and deploy output dir
• Parity check against the baseline
• Remove react-scripts / webpack deps and configs in a final commit, after user sign-off

index.html

<!-- project root: index.html -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" href="/favicon.ico" />          <!-- was %PUBLIC_URL%/favicon.ico -->
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>App</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/index.jsx"></script>
  </body>
</html>

Files in public/ keep working and are served from /. index.html must leave public/, or Vite copies it verbatim instead of processing it.

Config that matches CRA defaults

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import svgr from 'vite-plugin-svgr';
import { fileURLToPath, URL } from 'node:url';

export default defineConfig({
  plugins: [react(), svgr()],
  resolve: {
    // CRA's jsconfig "baseUrl": "src" allowed `import Button from 'components/Button'`
    alias: { components: fileURLToPath(new URL('./src/components', import.meta.url)) },
  },
  envPrefix: ['VITE_', 'REACT_APP_'],   // transitional: keep old names working, rename later
  server: {
    port: 3000,
    proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } }, // from "proxy" or setupProxy.js
  },
  build: { outDir: 'build' },           // keep the deploy pipeline unchanged for now
  test: {
    environment: 'jsdom',
    globals: true,                      // keeps Jest-style describe/it/expect without imports
    setupFiles: './src/setupTests.js',
  },
});

Add /// <reference types="vitest/config" /> at the top if TypeScript complains about test. Scripts become "dev": "vite", "build": "vite build", "preview": "vite preview", "test": "vitest".

Source conversions

webpack / CRA	Vite
process.env.REACT_APP_X	import.meta.env.REACT_APP_X (with envPrefix) then rename to VITE_X
process.env.NODE_ENV === 'production'	import.meta.env.PROD
process.env.PUBLIC_URL	import.meta.env.BASE_URL
require('./img.png')	import img from './img.png' or new URL('./img.png', import.meta.url).href
require.context('./locales', true, /\.json$/)	import.meta.glob('./locales/**/*.json', { eager: true })
module.hot.accept()	delete (React plugin handles Fast Refresh) or import.meta.hot
import { ReactComponent as Logo } from './logo.svg'	import Logo from './logo.svg?react' with vite-plugin-svgr v4+
JSX inside .js files	rename to .jsx (git mv keeps history); bulk rename with a script, then fix imports that include the extension
@import '~bootstrap/scss/bootstrap'	@import 'bootstrap/scss/bootstrap'
import worker from 'worker-loader!./w'	new Worker(new URL('./w.js', import.meta.url), { type: 'module' })
raw-loader	import text from './file.txt?raw'

For env access spread across many files, use a codemod or a careful sed with review; do not shim process.env globally with define, it hides missed conversions and can leak server-side variables into the bundle.

Loader and plugin mapping (custom webpack)

webpack	Vite equivalent
babel-loader + preset-react/typescript	Framework plugin; TS is transpiled natively (type-check separately with tsc --noEmit)
Custom Babel plugins (emotion, styled-components, React Compiler)	Configure through the installed @vitejs/plugin-react version’s documented Babel hook; check its README, the API changed across majors
css-loader modules	*.module.css works out of the box
sass-loader / less-loader	Install sass-embedded (or sass) / less; no loader config
file-loader / url-loader	Native asset imports; build.assetsInlineLimit (default 4 KiB)
DefinePlugin	define (JSON-encode values) or env vars
ProvidePlugin ($, React)	Explicit imports; automatic JSX runtime removes the need for React in scope
HtmlWebpackPlugin	Root index.html; multiple pages via build.rollupOptions.input (rolldownOptions on Vite 8)
CopyWebpackPlugin	public/, or vite-plugin-static-copy
splitChunks	Dynamic import() per route; manual chunking only if measured
Module Federation	@module-federation/vite; plan it as its own step
Node polyfills (webpack 4 auto)	Not provided. Replace the dependency or add specific polyfills
browserslist targeting old browsers	build.target; @vitejs/plugin-legacy if you truly need non-ESM browsers

Tests: Jest to Vitest

• jest.fn() to vi.fn(), jest.mock() to vi.mock() (hoisted the same way), jest.useFakeTimers() to vi.useFakeTimers(), jest.requireActual to await vi.importActual.
• @testing-library/jest-dom: import @testing-library/jest-dom/vitest in the setup file.
• CRA’s moduleNameMapper for CSS and images is unnecessary; Vitest handles them through Vite.
• If the suite is large, migrate tests in a follow-up PR and keep Jest temporarily with babel-jest; do not block the build migration on 2,000 test files.

Gotchas

• Vite dev serves native ESM: a CommonJS-only dependency that imports fine in webpack can fail in dev only. Add it to optimizeDeps.include.
• Circular imports that webpack tolerated can produce undefined at module init under ESM ordering. Fix the cycle; do not reorder imports until it works.
• Case-insensitive file systems hide import './Button' vs button.jsx mismatches that break on Linux CI. Build in CI before merging.
• Code that reads process.env at runtime in the browser was always a webpack fiction. If the app needs runtime config per environment, fetch it instead of rebuilding.
• homepage in package.json set CRA’s public path; in Vite it is base.
• Service workers from the CRA PWA template need vite-plugin-pwa; do not ship a stale service-worker.js that caches the old asset names.

Parity check

npm run build && npx vite preview --port 4173 --strictPort
python3 scripts/audit_webpack_usage.py .      # must exit 0
npx vitest run

• Every baseline route renders, no console errors, assets (fonts, images, SVG) load
• Env-dependent behaviour matches (API base URL, feature flags, analytics keys)
• Main entry size within about 10% of baseline, or the difference is explained
• CI builds from a clean clone; deploy config points at the right output dir

Deleting react-scripts, webpack.config.js, craco.config.js and changing the deploy output directory affect production: show the diff and get the user’s confirmation first.

Report

## webpack to Vite migration
- Build time: <before> -> <after>; dev cold start: <before> -> <after>
- Main entry: <size before> -> <size after>
- Env vars renamed: REACT_APP_X -> VITE_X (list)
- Dependencies removed / added: ...
- Audit script: exit 0
- Not migrated yet / follow-ups: <tests still on Jest, legacy browser support, ...>