Fixing the '@vitejs/plugin-react' Error in Vite + React
When starting a new Vite + React project, you might run into this error:
npm run dev
> tanstack-query-v5-demo@0.0.1 dev
> vite
failed to load config from C:\...\vite.config.ts
error when starting dev server:
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@vitejs/plugin-react'
This can be confusing, especially if you’re just setting up your project. Let’s break down why this happens, how to fix it, and what best practices to follow.
Why This Happens
Vite is a fast build tool, but it doesn’t know how to handle React JSX/TSX out of the box. That’s where the @vitejs/plugin-react
package comes in.
-
vite.config.ts
imports the plugin:
import react from '@vitejs/plugin-react';
- But if you never installed it, Vite throws
Cannot find package '@vitejs/plugin-react'
.
In short: the config references a plugin that isn’t in your node_modules
.
Quick Fix ✅
Run:
npm i -D @vitejs/plugin-react
Other package managers:
pnpm add -D @vitejs/plugin-react
yarn add -D @vitejs/plugin-react
If It Still Doesn’t Work 🛠️
Sometimes node_modules get messy. Try a clean reinstall:
rm -rf node_modules package-lock.json
npm cache verify
npm i
Also confirm your Node.js version:
node -v
👉 Vite 5 requires Node.js >= 18.0.0.
Correct devDependencies
Make sure your package.json
includes the plugin:
"devDependencies": {
"@vitejs/plugin-react": "^4.3.1",
"vite": "^5.4.0",
"typescript": "^5.5.4",
"vitest": "^2.0.5",
"@testing-library/react": "^16.0.0",
"@testing-library/jest-dom": "^6.5.0",
"@testing-library/user-event": "^14.6.1",
"@types/react": "^18.3.4",
"@types/react-dom": "^18.3.0",
"jsdom": "^25.0.0"
}
Mental Model 🧠
Think of Vite like this:
- Vite Core → understands ES modules, static assets, TypeScript.
- Plugins → teach Vite how to handle JSX, React Fast Refresh, SWC, etc.
- @vitejs/plugin-react → is the bridge between React and Vite.
No plugin → no JSX → error.
Pro Tips
- Always check your
vite.config.ts
matches your dependencies. - If you fork or download a project, run
npm i
beforenpm run dev
. - Use the latest Node.js LTS (≥18).
- For performance, consider
@vitejs/plugin-react-swc
(faster builds with SWC).
Conclusion
This error is common when starting out with Vite + React:
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@vitejs/plugin-react'
The fix is simple:
- Install
@vitejs/plugin-react
- Verify Node.js ≥ 18
- Clean
node_modules
if needed
With that, your Vite + React app will run smoothly.
✍️ Written by: Cristian Sifuentes — Full-stack developer & AI/JS enthusiast, passionate about React, TypeScript, and scalable architectures.
✅ Tags: #react #vite #frontend #programming #devtools
Top comments (0)