Why Your React App Feels Slow and What to Do About It
You started your project with Create React App (CRA). It was the official, recommended way to bootstrap a React application for years. It handled the complex Webpack configuration, gave you a live development server, and produced a production-ready build. For a long time, it was perfect.
But lately, you’ve noticed the cracks. The initial server start takes what feels like an eternity. Every time you save a file, there’s a noticeable lag before the browser reflects your changes. Your production builds are becoming a coffee-break activity. You hear other developers talking about near-instantaneous Hot Module Replacement (HMR) and builds that finish in seconds, not minutes.
You’re not imagining it. The web development tooling landscape has evolved dramatically. The tool enabling those blazing-fast experiences is likely Vite. Born out of the need for a faster, leaner development experience for modern web projects, Vite has become the new standard. It uses native ES modules served directly to the browser during development, eliminating the bundling step that bogs down tools like Webpack.
If your CRA project is feeling sluggish, converting it to Vite is one of the most impactful performance upgrades you can make. The process is straightforward, largely automated, and the payoff in developer experience is immediate and substantial. This guide will walk you through the complete, safe migration.
Understanding the Shift From Webpack to Vite
Before diving into the conversion, it helps to know what’s changing under the hood. Create React App uses Webpack as its bundler. Webpack is powerful and mature, but its architecture requires it to crawl your entire dependency graph, bundle it, and then serve it to the browser. This happens on server start and, to a lesser extent, on every file change.
Vite takes a different approach. In development, it leverages your browser’s native support for ES Modules. Instead of bundling everything upfront, Vite serves your source code as native ES modules. The browser itself handles the imports. Vite only transforms and serves source files on-demand, as the browser requests them. This makes server start instantaneous and HMR updates incredibly fast.
For production, Vite uses Rollup, a highly efficient bundler, to create optimized static assets. The result is often a smaller, faster production build than what Webpack produces. The mental model shift is from “bundled-first” to “native-first, then bundled for production.”
What You Gain With Vite
The benefits of migrating are concrete and measurable.
– Instant server start: Your dev server is ready in milliseconds, not seconds.
– Lightning-fast HMR: File changes appear in the browser almost as fast as you can save.
– Optimized builds: Production builds are generally faster and can produce smaller output.
– Out-of-the-box support: Modern features like TypeScript, JSX, CSS Modules, and PostCSS work without extra configuration.
– Simpler configuration: The `vite.config.js` file is typically much simpler than a comparable `webpack.config.js`.
Preparing Your Create React App for Migration
A successful migration starts with preparation. First, ensure your project is in a clean state. Commit all your current changes to Git or your version control system. This gives you a safe point to return to if anything goes wrong. Create a new branch, like `migrate-to-vite`, to isolate your work.
Next, audit your project’s dependencies and configuration. CRA projects often accumulate custom scripts, environment variables, and Webpack plugins over time. You’ll need to map these to their Vite equivalents.
Open your `package.json` and note the following:
– The `react-scripts` package is the heart of CRA. You will be removing it.
– Any Webpack-related plugins or loaders (e.g., `craco`, `react-app-rewired`) will need re-evaluation.
– Check for any special Babel plugins or PostCSS configurations.
– Review your `scripts` section: `start`, `build`, `test`, `eject`.
Also, locate your environment variable files (`.env`, `.env.development`, `.env.production`). Vite handles these slightly differently, but the migration is simple.
Installing the Vite Migration Tool
The React team provides an official tool to automate much of this process. In your project root, run the following command. It will analyze your CRA project and generate a migration report.
`npx @react/plugin-create-react-app`
Follow the interactive prompts and select the option to migrate to Vite. The tool will output a summary of required changes. While it won’t perform the migration for you, it gives you a precise checklist. For this guide, we’ll perform the migration manually, which gives you more control and understanding.
Step-by-Step Migration Process
Now, let’s convert the project. We’ll replace CRA’s core dependencies with Vite’s and update the configuration.
1. Remove Create React App Dependencies
First, uninstall the `react-scripts` package and any CRA-specific config packages.
`npm uninstall react-scripts`
If you have `craco` or `react-app-rewired`, uninstall those as well.
`npm uninstall craco`
2. Install Vite and Its React Plugin
Vite itself is a framework-agnostic build tool. You need the core `vite` package and the official React plugin to handle JSX and Fast Refresh.
`npm install vite @vitejs/plugin-react –save-dev`
You may also want to install the `@types/node` package to get better type support for Node.js APIs in your Vite config file if you’re using TypeScript.
`npm install @types/node –save-dev`
3. Update Your package.json Scripts
Replace the CRA scripts in your `package.json` with their Vite equivalents. The `test` script often remains the same if you’re using Jest.
“`json
“scripts”: {
“dev”: “vite”,
“build”: “vite build”,
“preview”: “vite preview”,
“test”: “react-scripts test”
}
“`
– `dev`: Starts the Vite development server.
– `build`: Creates an optimized production build.
– `preview`: Serves the production build locally for testing.
– `test`: We’ll address testing setup later.
4. Create the Vite Configuration File
Create a `vite.config.js` (or `vite.config.ts`) file in your project root. This is where you configure Vite. A basic configuration for a React project is minimal.
“`javascript
import { defineConfig } from ‘vite’
import react from ‘@vitejs/plugin-react’
export default defineConfig({
plugins: [react()],
})
<p>If your project uses TypeScript, Vite has built-in support. No extra plugin is needed for `.tsx` files.</p>
<h3>5. Move and Update Your Index.html File</h3>
<p>This is a crucial step. In a CRA project, the `public/index.html` file is a template. In Vite, `index.html` is the actual entry point and sits in the project root, not inside a `public` folder.</p>
<p>Move `public/index.html` to the root of your project (the same level as `package.json`). Then, you must update it.</p>
<p>Remove the `%PUBLIC_URL%` placeholders. In Vite, absolute paths are relative to the project root. Change the line that includes your JavaScript.</p>
<p>From this CRA-style line:</p>
<p>`<script src="%PUBLIC_URL%/index.js"></script>`</p>
<p>To this Vite-style line:</p>
<p>`<script type="module" src="/src/index.jsx"></script>`</p>
<p>Note the `type="module"` and the direct path to your source entry file. Also, remove any `<link>` tags that reference `%PUBLIC_URL%` and update them to absolute paths starting with `/`.</p>
<h3>6. Update Environment Variables</h3>
<p>Vite exposes environment variables on a special `import.meta.env` object instead of `process.env`. The naming convention also changes slightly.</p>
<p>Variables prefixed with `VITE_` are exposed. For example, `VITE_API_KEY` becomes available as `import.meta.env.VITE_API_KEY`.</p>
<p>Rename your `.env` files accordingly. Change `REACT_APP_API_URL` to `VITE_API_URL`. Then, search your source code for `process.env` and update all references to `import.meta.env`.</p>
<h3>7. Adjust Import Paths for Assets</h3>
<p>Vite handles static assets differently. Imports for images, fonts, and other files should use absolute paths relative to the project root or use the new `?url` and `?raw` query suffixes if you need the URL or raw content.</p>
<p>For example, if you had:</p>
<p>`import logo from './logo.png'`</p>
<p>It will likely still work, as Vite will treat it as a static asset import. However, for assets inside `public`, reference them with an absolute path starting with `/`.</p>
<h2>Addressing Common Post-Migration Issues</h2>
<p>After completing the core steps, run `npm run dev`. You might encounter some errors. Here are the most common fixes.</p>
<h3>JSX File Extensions</h3>
<p>Vite, by default, expects files containing JSX to have the `.jsx` or `.tsx` extension. If your entry file is `src/index.js`, rename it to `src/index.jsx`. Update the reference in your root `index.html` file accordingly.</p>
<p>Similarly, rename any other `.js` files that contain JSX to `.jsx`.</p>
<h3>Absolute Imports and Path Aliases</h3>
<p>CRA supports absolute imports from `src` (e.g., `import Button from 'components/Button'`). To enable this in Vite, add a resolve alias to your `vite.config.js`.</p>
<p>```javascript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'
export default defineConfig({
plugins: [react()],
resolve: {
alias: {
'@': path.resolve(__dirname, './src'),
},
},
})
```</p>
<p>Now you can use `import Button from '@/components/Button'`. You can also replicate the exact CRA behavior by setting the alias for `src`.</p>
<h3>Setting Up the Testing Environment</h3>
<p>The `react-scripts test` command uses Jest under the hood. Since we removed `react-scripts`, the `test` script will break. You have two main options.</p>
<p>First, you can re-install Jest and its dependencies separately and configure it to work with Vite's build process. This is more complex.</p>
<p>The simpler, modern approach is to adopt Vitest, a test runner built from the ground up to work seamlessly with Vite. It shares the same configuration and has a Jest-compatible API.</p>
<p>Install Vitest and the Vitest JS DOM environment.</p>
<p>`npm install vitest jsdom @testing-library/react @testing-library/jest-dom --save-dev`</p>
<p>Update your `vite.config.js` to define a test configuration.</p>
<p>```javascript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({
plugins: [react()],
test: {
globals: true,
environment: 'jsdom',
setupFiles: './src/setupTests.js',
},
})
```</p>
<p>Finally, update your `package.json` test script.</p>
<p>`"test": "vitest"`</p>
<p>Your existing React Testing Library tests may work with little to no modification.</p>
<h3>Handling SVGs and Other Custom Assets</h3>
<p>If you were using a custom Webpack loader to import SVGs as React components, you'll need a Vite plugin. Install `vite-plugin-svgr`.</p>
<p>`npm install vite-plugin-svgr --save-dev`</p>
<p>Then, add it to your Vite config.</p>
<p>```javascript
import svgr from 'vite-plugin-svgr'
export default defineConfig({
plugins: [react(), svgr()],
})
```</p>
<p>Now you can import SVGs as components: `import { ReactComponent as Logo } from './logo.svg'`.</p>
<h2>Verifying the Migration and Next Steps</h2>
<p>Once all errors are resolved and the development server starts, thoroughly test your application.</p>
<p>- Navigate through all major features and pages.
- Test Hot Module Replacement by making a small CSS and JS change.
- Run your test suite (`npm test`).
- Create a production build (`npm run build`) and preview it (`npm run preview`).</p>
<p>Check the build output in the `dist` folder. Compare its size and structure to your old CRA `build` folder. You should see a comparable or smaller bundle.</p>
<p>Finally, update your deployment configuration if necessary. Most platforms that support Node.js (Vercel, Netlify, Render) support Vite out of the box. You may just need to update the build command in your project settings to `npm run build` and the output directory to `dist`.</p>
<h3>Exploring Advanced Vite Features</h3>
<p>With the migration complete, you can now leverage Vite's full potential. Consider exploring:</p>
<p>- Library Mode: Easily build your React components as a reusable library.
- CSS Preprocessors: Built-in support for Sass, Less, and Stylus with just an `npm install`.
- Environment Variables: More granular control over dev vs. prod variables.
- Dynamic Imports: Automatic code-splitting for better performance.</p>
<p>Your development workflow is now significantly faster and more modern. The initial investment in migration pays daily dividends in saved time and reduced frustration, allowing you to focus on building your application, not waiting for your tools.</p>