기존에 Create React App(CRA)로 개발해온 프로젝트를 Vite로 마이그레이션하면서 겪은 삽질과 해결 과정을 정리했습니다. 실제 에러 메시지와 해결 과정을 그대로 담았기 때문에, 비슷한 작업을 하려는 분들에게 도움이 될 수 있을 겁니다.
1. CRA에서 Vite로 전환 이유
- CRA 빌드 속도에 불만
- HMR이 느림
- config override가 귀찮음
- 최신 생태계는 Vite를 지향하는 추세
2. 초기 설정
npm create vite@latest- 템플릿은 react + javascript 선택
- 기존 CRA 구조와 맞추기 위해 디렉토리 구조는 유지
기존 public/, src/ 그대로 복사 후 시작
3. entry 파일 변경 (main.js → main.jsx)
CRA에서는 index.js 또는 main.js 를 entry로 썼지만, Vite에서는 기본이 .jsx 또는 .tsx이다.
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import { AuthProvider } from './AuthContext';
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
<AuthProvider>
<App />
</AuthProvider>
);✅ Vite에서 JSX가 포함된 파일은 반드시 .jsx 확장자로!
4. HTML 파일 문제 (index.html)
CRA는 /public/index.html을 사용하지만, Vite는 루트 디렉토리에 index.html이 있어야 한다.
<!-- 최상단 루트에 위치 -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Vite App</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.jsx"></script>
</body>
</html>%PUBLIC_URL% 같은 문법은 제거해야 함.
5. JSX 구문 에러 발생
[plugin:vite:import-analysis] Failed to parse source for import analysis because the content contains invalid JS syntax. If you are using JSX, make sure to name the file with the .jsx or .tsx extension.✅ 모든 JSX가 포함된 파일의 확장자를 .jsx로 변경해야 함 (ex: App.js → App.jsx)
6. 외부 라이브러리 에러 (ex: web-vitals, gridjs-react)
CRA에서 쓰던 일부 라이브러리는 Vite에서 바로 동작하지 않을 수 있음
Failed to resolve import "web-vitals"해결 방법:
- yarn add web-vitals
- 또는 사용하지 않는다면 해당 import 제거
또는 gridjs-react 같이 ESM 지원이 불완전한 라이브러리는 에러 발생:
TypeError: chart.addCandlestickSeries is not a function✅ 라이브러리 import 시 named export가 제대로 되어 있는지 확인 필요
7. Emotion 관련 에러
Failed to resolve import "@emotion/styled"해결:
yarn add @emotion/react @emotion/styled8. WebSocket 관련 에러 (SSL 환경에서)
Mixed Content: attempted to connect to the insecure WebSocket endpoint 'ws://...'해결:
- vite.config.js에 다음 추가:
server: {
hmr: {
protocol: 'wss',
host: '도메인명'
},
https: true,
port: 3000,
allowedHosts: ['도메인명']
}- 그리고 nginx 설정도 proxy_set_header Upgrade $http_upgrade; 설정 등 WebSocket 처리를 제대로 해야 함
9. 개발서버 접근 오류
Blocked request. This host ("도메인") is not allowed.vite.config.js에 server.allowedHosts 추가 필요
server: {
allowedHosts: ["도메인"]
}10. 삽질하면서 배운 점들
- CRA와 Vite는 동작 구조가 많이 다름 (index.html 위치부터 entry 방식까지)
- Vite는 빠르고 좋지만, JSX 파일 확장자에 민감함
- 일부 라이브러리는 ESM 호환이 부족해서 아예 제거하거나 다른 방식으로 대체 필요
- WebSocket이나 HMR 설정도 환경에 따라 커스터마이징 필요
11. 결론
Vite로의 전환은 초기 설정이 다소 번거롭고 예상치 못한 문제들이 있었지만, 결과적으로 빌드 속도나 개발자 경험은 훨씬 개선됨.
지금 이 글을 읽고 있다면... 당신은 나보다 훨씬 덜 삽질하고 있을 가능성이 높습니다 :)