Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 38 ยท Migration and Alternatives

Migrating from Webpack to Vite

Move a webpack project to Vite step by step: entry HTML, aliases, env variables, DefinePlugin, dev server proxy, asset imports, require calls and CommonJS gotchas.

If you decide that Vite is a better fit than webpack for a project, the move is manageable: most concepts map one to one. The work lies in the details that webpack handled implicitly: require() calls, environment variables, loader-specific import syntax, and global polyfills. This lesson gives a mapping table, a conversion order that keeps the app working, and a list of problems you will probably meet. For the reasoning behind the choice, see Webpack vs Vite.

Webpack and Vite do not run on this site. The configs here are read-only. The TryIt blocks are Node.js stand-ins: one converts a webpack config object into a Vite config object, and one rewrites process.env and require usage in source text. They show the mapping logic, not a complete migration tool.

The core difference to keep in mind

Webpack starts from a JavaScript entry (entry: './src/index.js') and writes an HTML file via HtmlWebpackPlugin. Vite starts from an index.html at the project root, which references your entry with a script tag. Vite also serves modules natively during development, so every file must be valid ES module syntax with resolvable imports.

HTML
<!-- index.html at the project root -->
<!doctype html>
<html lang="en">
  <head><meta charset="UTF-8" /><title>My app</title></head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/index.jsx"></script>
  </body>
</html>

Concept mapping

Webpack Vite
entry + HtmlWebpackPlugin index.html with <script type="module">
output.path build.outDir
output.publicPath base
resolve.alias resolve.alias
resolve.extensions resolve.extensions (rarely needed; write extensions in imports)
DefinePlugin define
process.env.X import.meta.env.VITE_X
devServer.proxy server.proxy
devServer.port / open server.port / server.open
babel-loader + presets built in (esbuild); plugins such as @vitejs/plugin-react
css-loader, style-loader, sass-loader built in; install sass only
file-loader / asset modules built in; ?url, ?raw suffixes
MiniCssExtractPlugin built in (CSS extracted automatically in builds)
splitChunks build.rollupOptions.output.manualChunks
devtool build.sourcemap
performance.hints build.chunkSizeWarningLimit

Step by step

  1. Create a branch and install: npm install -D vite @vitejs/plugin-react (or the plugin for your framework).
  2. Move or create index.html at the root with the module script tag. Replace %PUBLIC_URL% placeholders (Create React App style) with / paths.
  3. Add vite.config.js with plugins, aliases, define and proxy settings.
  4. Convert environment variables. Rename process.env.REACT_APP_API to import.meta.env.VITE_API, and rename the .env entries. Only variables starting with VITE_ are exposed to client code.
  5. Fix imports: extensions on JSX files (.jsx rather than .js containing JSX), no require(), no webpack-specific features such as require.context (use import.meta.glob).
  6. Replace scripts in package.json: "dev": "vite", "build": "vite build", "preview": "vite preview".
  7. Run, fix, compare. Build both ways and compare size and behaviour. Remove webpack packages only after everything passes.

A config conversion stand-in

Node.js Stand-in: webpack config to Vite config

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Environment variables

Webpack projects often rely on process.env.X replaced at build time. Vite exposes values through import.meta.env:

JavaScript
// before
const api = process.env.REACT_APP_API_URL;
// after
const api = import.meta.env.VITE_API_URL;

Vite also provides import.meta.env.MODE, DEV, PROD and BASE_URL. If a library you cannot change reads process.env.NODE_ENV, Vite replaces that specific expression for you; other process.env access needs a define entry.

Node.js Stand-in: rewrite env access and require calls

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Common problems

  • require is not defined. Vite does not support CommonJS in your own source. Convert to import. For dependencies, Vite pre-bundles them with esbuild, which handles most CommonJS.
  • global is not defined or Buffer/process missing. Use define: { global: 'globalThis' } or remove the dependency's need for it; avoid Node built-ins in browser code.
  • JSX in .js files. Rename to .jsx, or configure esbuild: { loader: 'jsx', include: /src\/.*\.js$/ } as a stop-gap.
  • require.context. Replace with import.meta.glob('./pages/*.jsx'), which gives lazy imports.
  • Loader query strings (import x from '!!raw-loader!./file.txt'). Use ./file.txt?raw.
  • Different CSS-modules behaviour or order. Check styles visually; ensure *.module.css naming.
  • Webpack-only plugins (Module Federation, special analyzers) need Vite equivalents such as @originjs/vite-plugin-federation and rollup-plugin-visualizer.
  • Chunking differences. Re-check bundle size and recreate manual chunks:
JavaScript
build: {
  rollupOptions: {
    output: {
      manualChunks: { react: ['react', 'react-dom'] },
    },
  },
},

Rolling out safely

Keep both builds working during the transition: add Vite scripts next to webpack's and let CI run both for a while. Compare the production output in a staging environment, check lazy routes, environment-specific URLs and source maps, then switch the deploy and delete the webpack config. A big-bang rewrite is rarely necessary.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does a Vite project start, compared with webpack's entry option?

    Vite uses HTML as the entry point, with <script type='module' src='/src/...'> referencing your code.
  2. 2. How do you expose an environment variable to client code in Vite?

    Only variables whose names start with VITE_ are exposed, which prevents accidental leaks of secrets.
  3. 3. What replaces require.context in Vite?

    import.meta.glob matches files by pattern and returns lazy (or eager) imports.
  4. 4. Which approach to the migration is safest?

    Keeping both builds lets you compare output and roll back easily.

Summary

  • Vite starts from index.html; most webpack options have a direct Vite equivalent.
  • Convert process.env to import.meta.env.VITE_*, require to import, require.context to import.meta.glob.
  • Replace loader-specific imports with query suffixes such as ?raw and ?url.
  • Migrate incrementally and compare builds before removing webpack.

Next: Project: Build a Mini Bundler