최근 많은 개발자들이 React 프로젝트를 생성할 때 Vite를 선택하고 있습니다. Vite는 빠른 빌드 속도와 간편한 설정으로 인해 많은 인기를 끌고 있습니다.
하지만 Vite를 이용해 React 프로젝트를 설정하는 과정에서 여러 오류가 발생할 수 있습니다. 이 글에서는 React Vite 환경에서 SPA(Single Page Application) 프로젝트를 세팅하는 방법과 함께 발생할 수 있는 몇 가지 오류를 해결하는 방법에 대해 설명하겠습니다.
Vite 설치 및 기본 설정
Vite를 사용하여 React 프로젝트를 만들기 위해서는 먼저 Vite를 설치해야 합니다. Vite는 Node.js 환경에서 실행되므로 Node.js가 설치되어 있어야 합니다.
Node.js 설치 후, 다음과 같이 Vite를 프로젝트에 설치하는 과정을 진행할 수 있습니다.
Vite 설치 과정
- Vite 설치하기
Vite를 글로벌하게 설치하기 위해 아래의 명령어를 터미널에 입력합니다.
bash
npm install -g create-vite
- 새로운 프로젝트 폴더 생성
새로운 React 프로젝트를 위한 폴더를 생성하고 해당 폴더로 이동합니다.
bash
mkdir my-react-app
cd my-react-app
- React 애플리케이션 생성
아래의 명령어를 실행하여 새로운 React 애플리케이션을 생성합니다.
bash
npm create vite@latest my-app -- --template react
이 명령어를 통해 Vite의 템플릿을 사용하여 React 애플리케이션을 생성할 수 있습니다.
- 의존성 설치
생성된 프로젝트 폴더로 이동한 후, 의존성을 설치합니다.
bash
cd my-app
npm install
- 개발 서버 실행
다음 명령어로 개발 서버를 실행합니다.
bash
npm run dev
이제 개발 서버가 실행되면, 브라우저에서 http://localhost:5173에 접속하여 React 애플리케이션을 확인할 수 있습니다.
| 단계 | 명령어 |
|---|---|
| Vite 설치 | npm install -g create-vite |
| 폴더 생성 | mkdir my-react-app |
| 프로젝트 생성 | npm create vite@latest my-app -- --template react |
| 의존성 설치 | npm install |
| 개발 서버 실행 | npm run dev |
발생할 수 있는 오류 및 해결 방법
Vite를 통해 React 프로젝트를 생성하는 과정에서 여러 오류가 발생할 수 있습니다. 다음은 자주 발생하는 오류와 그 해결 방법에 대한 설명입니다.
개발 서버 실행 시 오류
개발 서버를 실행했을 때, http://localhost:3000에서 접근이 불가능하고 http://localhost:5173에서 개발 서버가 열리는 경우가 있습니다. 이러한 상황에서 다음과 같은 오류 메시지가 나타날 수 있습니다.
- non-JS module files deprecated
이 오류는 Vite의 동작 방식 변화와 관련이 있습니다. Vite는 기본적으로 non-JavaScript 모듈 파일(CSS, 이미지 등)을 지원하지 않으므로, 이러한 파일을 처리하기 위해서는 별도의 플러그인을 사용해야 합니다.
해결 방법
이 문제를 해결하기 위해서는 vite-plugin-react-pages 플러그인을 설치하여 non-JavaScript 모듈을 처리할 수 있도록 설정합니다.
- 플러그인 설치
다음 명령어로 플러그인을 설치합니다.
bash
npm install vite-plugin-react-pages
- vite.config.js 파일 수정
프로젝트의 루트 디렉토리에 vite.config.js 파일을 생성하고, 다음과 같이 수정합니다.
“`javascript
import { defineConfig } from ‘vite’;
import react from ‘@vitejs/plugin-react’;
import { reactPages } from ‘vite-plugin-react-pages’;
export default defineConfig({
plugins: [react(), reactPages()],
});
“`
위의 과정을 통해 non-JavaScript 모듈 파일을 처리할 수 있게 되며, 개발 서버를 정상적으로 실행할 수 있습니다.
| 오류 메시지 | 원인 | 해결 방법 |
|---|---|---|
| non-JS module files deprecated | Vite가 non-JavaScript 모듈을 기본 지원하지 않음 | vite-plugin-react-pages 플러그인 설치 |
또 다른 오류 발생: @vitejs/plugin-react
개발 서버 실행 후, 다음과 같은 오류 메시지가 발생할 수 있습니다.
- Can’t find an instance of @vitejs/plugin-react
이 오류는 Vite가 React 애플리케이션에서 MDX(Markdown + JSX) 파일을 지원하기 위해 필요한 @vitejs/plugin-react 플러그인을 찾을 수 없다는 것을 의미합니다.
해결 방법
이 문제를 해결하기 위해서는 @vitejs/plugin-react 플러그인을 설치하고, vite.config.js 파일에 추가해야 합니다.
- 플러그인 설치
다음 명령어로 플러그인을 설치합니다.
bash
npm install @vitejs/plugin-react
- vite.config.js 파일 수정
vite.config.js 파일에 아래와 같이 플러그인을 추가합니다.
“`javascript
import { defineConfig } from ‘vite’;
import react from ‘@vitejs/plugin-react’;
export default defineConfig({
plugins: [react()],
});
“`
이렇게 하면 오류가 수정되고 React 애플리케이션에서 MDX 파일을 사용할 수 있습니다.
| 오류 메시지 | 원인 | 해결 방법 |
|---|---|---|
| Can’t find an instance of @vitejs/plugin-react | Vite가 MDX 파일을 처리하는 플러그인을 찾지 못함 | @vitejs/plugin-react 플러그인 설치 및 설정 |
Vite와 CRA의 차이점 및 최적화
Vite와 Create React App(CRA)은 각각의 장단점을 가지고 있습니다. Vite는 빠른 빌드 속도와 직관적인 설정으로 인해 점점 더 많은 개발자들이 선택하고 있지만, CRA는 이미 많은 프로젝트에 활용되고 있습니다.
Vite의 주된 장점은 다음과 같습니다.
- 빠른 개발 서버: Vite는 ES 모듈을 사용하여 빠른 개발 서버를 제공합니다.
- 간편한 설정: Vite는 기본적으로 다양한 플러그인을 지원하므로, 개발자가 필요한 기능을 쉽게 추가할 수 있습니다.
- 최신 기술 지원: Vite는 최신 JavaScript 기능을 지원하며, TypeScript와의 호환성도 뛰어납니다.
하지만 CRA는 많이 알려져 있고, 기존 프로젝트와의 호환성 문제로 인해 여전히 많은 프로젝트에서 사용되고 있습니다. 이러한 점에서 Vite로 마이그레이션할 때는 각 프로젝트의 특성과 필요에 따라 신중히 생각해야 합니다.
| 비교 항목 | Vite | CRA |
|---|---|---|
| 빌드 속도 | 매우 빠름 | 상대적으로 느림 |
| 설정 편의성 | 직관적, 다양한 플러그인 지원 | 기본 설정이 복잡할 수 있음 |
| 문서화 및 커뮤니티 | 상대적으로 적음 | 방대한 자료와 지원 |
결론
React Vite 환경에서 SPA 프로젝트를 설정하는 과정은 간단하지만, 여러 오류가 발생할 수 있습니다. 이 글에서는 Vite를 설치하고 기본 설정하는 방법, 그리고 자주 발생하는 오류를 해결하는 방법에 대해 설명하였습니다.
Vite의 빠른 속도와 간편한 설정 덕분에 많은 개발자들이 이 도구를 선택하고 있으며, 앞으로도 더 많은 자료와 커뮤니티가 생길 것으로 예상됩니다. Vite를 사용하여 React 프로젝트를 설정하고, 발생하는 오류를 해결하는 데 이 글이 도움이 되길 바랍니다.
