DEV Community

Neweraofcoding
Neweraofcoding

Posted on

Migrating from Create React App to Vite (Complete Guide)

#javascript #webdev #programming #productivity

Modern React development has evolved significantly. Many projects that were initially created using Create React App (CRA) are now migrating to Vite for faster builds, improved developer experience, and fewer dependency issues.

If your project uses react-scripts and you’re facing slow startup, build issues, or vulnerability warnings, migrating to Vite can be a great improvement.

This guide explains how to migrate a React project from Create React App to Vite, including all common pitfalls such as environment variables, public assets, scripts, and configuration changes.

Why Move from Create React App to Vite?

Create React App was once the standard way to start a React project. However, it has several limitations today:

  • Slow development server startup
  • Large dependency tree
  • Frequent npm audit vulnerabilities
  • Webpack-based builds that are slower than modern bundlers
  • Limited customization without ejecting

Vite solves these problems by using ESBuild for development and Rollup for production builds.

Key benefits include:

  • Instant dev server startup
  • Faster hot module replacement (HMR)
  • Smaller dependency tree
  • Simpler configuration
  • Modern tooling

Step 1: Remove Create React App Dependencies

CRA projects depend on react-scripts, which powers the development and build processes.

Remove it from your project:

npm uninstall react-scripts
Enter fullscreen mode Exit fullscreen mode

You may also remove testing libraries if you plan to configure testing later:

npm uninstall @testing-library/jest-dom @testing-library/react @testing-library/user-event
Enter fullscreen mode Exit fullscreen mode

Step 2: Install Vite and React Plugin

Install Vite and the React plugin required to support JSX and React Fast Refresh.

npm install -D vite @vitejs/plugin-react
Enter fullscreen mode Exit fullscreen mode

If your project uses TypeScript:

npm install -D typescript
Enter fullscreen mode Exit fullscreen mode

Step 3: Update Package Scripts

In CRA projects, scripts look like this:

"scripts": {
  "start": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "eject": "react-scripts eject"
}
Enter fullscreen mode Exit fullscreen mode

Replace them with Vite scripts:

"scripts": {
  "dev": "vite",
  "build": "vite build",
  "preview": "vite preview"
}
Enter fullscreen mode Exit fullscreen mode

Now the development server will run using:

npm run dev
Enter fullscreen mode Exit fullscreen mode

Step 4: Create the Vite Configuration

Create a file named vite.config.ts in the project root.

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()]
})
Enter fullscreen mode Exit fullscreen mode

This enables React support and hot module reloading.

Step 5: Move index.html to the Root Folder

In Create React App, index.html is located inside the public folder.

public/index.html
Enter fullscreen mode Exit fullscreen mode

In Vite, index.html must be placed in the project root.

project
 ├─ index.html
 ├─ src
 └─ public
Enter fullscreen mode Exit fullscreen mode

Step 6: Replace index.tsx with main.tsx

CRA uses:

src/index.tsx
Enter fullscreen mode Exit fullscreen mode

Vite typically uses:

src/main.tsx
Enter fullscreen mode Exit fullscreen mode

Rename the file and update the content:

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);
Enter fullscreen mode Exit fullscreen mode

Step 7: Fix PUBLIC_URL Assets

One of the most common migration issues is the use of:

%PUBLIC_URL%
Enter fullscreen mode Exit fullscreen mode

Example from CRA:

<link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
<link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
<link rel="apple-touch-icon" href="%PUBLIC_URL%/logo192.png" />
Enter fullscreen mode Exit fullscreen mode

Vite does not support %PUBLIC_URL%.

Instead, place assets inside the public folder and reference them directly:

public/
 ├─ favicon.ico
 ├─ logo192.png
 └─ manifest.json
Enter fullscreen mode Exit fullscreen mode

Then update the HTML:

<link rel="icon" href="/favicon.ico" />
<link rel="manifest" href="/manifest.json" />
<link rel="apple-touch-icon" href="/logo192.png" />
Enter fullscreen mode Exit fullscreen mode

Step 8: Update Environment Variables

CRA environment variables use the prefix:

REACT_APP_
Enter fullscreen mode Exit fullscreen mode

Example:

REACT_APP_API_URL
Enter fullscreen mode Exit fullscreen mode

In Vite, environment variables must start with:

VITE_
Enter fullscreen mode Exit fullscreen mode

Example:

VITE_API_URL
Enter fullscreen mode Exit fullscreen mode

Access them using:

import.meta.env.VITE_API_URL
Enter fullscreen mode Exit fullscreen mode

Step 9: Clean Install Dependencies

After making configuration changes, perform a clean install.

rm -rf node_modules
rm package-lock.json
npm install
Enter fullscreen mode Exit fullscreen mode

Then start the dev server:

npm run dev
Enter fullscreen mode Exit fullscreen mode

The app will run on:

http://localhost:5173
Enter fullscreen mode Exit fullscreen mode

Step 10: Fix React Version Compatibility

Create React App works best with React 18. If your project contains an unsupported version, update it:

"react": "^18.2.0",
"react-dom": "^18.2.0"
Enter fullscreen mode Exit fullscreen mode

Then reinstall dependencies.

Common Issues During Migration

Blank Page in Browser

Check the browser console for errors and verify that:

  • index.html is in the root folder
  • the script path is correct 
<script type="module" src="/src/main.tsx"></script>
Enter fullscreen mode Exit fullscreen mode

Static Files Not Loading

Ensure assets are inside the public folder and referenced with /.

Incorrect:

%PUBLIC_URL%/image.png
Enter fullscreen mode Exit fullscreen mode

Correct:

/image.png
Enter fullscreen mode Exit fullscreen mode

Environment Variables Not Working

Make sure variables use the correct prefix.

Incorrect:

process.env.REACT_APP_API
Enter fullscreen mode Exit fullscreen mode

Correct:

import.meta.env.VITE_API
Enter fullscreen mode Exit fullscreen mode

Recommended Folder Structure 

project
 ├─ public
 │   ├─ favicon.ico
 │   └─ manifest.json
 │
 ├─ src
 │   ├─ components
 │   ├─ pages
 │   ├─ App.tsx
 │   └─ main.tsx
 │
 ├─ index.html
 ├─ package.json
 └─ vite.config.ts
Enter fullscreen mode Exit fullscreen mode

Final Thoughts

Migrating from Create React App to Vite can dramatically improve development speed and simplify project maintenance. The process mainly involves replacing build tools, updating environment variables, fixing public assets, and adjusting the project structure.

Once migrated, developers benefit from faster builds, modern tooling, and a cleaner dependency ecosystem.

If you are starting a new React project today, Vite is widely considered one of the best options available for building modern web applications.

Top comments (0)