React npx 오류 해결 및 Vite 설치 방법 안내

최근 React 프로젝트를 설정하는 과정에서 Vite를 사용하여 SPA(Single Page Application)를 구축하려는 개발자들이 많아지고 있습니다. 하지만 이 과정에서 발생할 수 있는 여러 오류와 그 해결 방법에 대해 알아보겠습니다.

이 글에서는 React npx 오류 해결 방법과 Vite 설치 절차를 자세히 설명드리겠습니다.

Vite란 무엇인가?

Vite는 차세대 프론트엔드 도구로, 빠른 개발 서버와 최적화된 빌드 프로세스를 제공합니다. Vite는 ES 모듈을 기반으로 하여, 개발 중에는 브라우저가 직접 모듈을 로드하도록 하여 빠른 HMR(Hot Module Replacement)을 가능하게 합니다.

Vite는 또한 Rollup을 기반으로 하여, 배포 시에는 최적화된 정적 리소스를 생성합니다. 이러한 특성 덕분에 Vite는 많은 개발자들에게 인기를 끌고 있습니다.

기능	Vite의 특징
개발 서버	매우 빠른 HMR 지원
빌드 도구	Rollup 기반으로 최적화된 빌드
모듈 처리	ES 모듈을 사용하여 브라우저가 직접 로드
지원 언어	JavaScript, TypeScript, JSX 등 다양한 언어 지원

Vite 설치 및 React 프로젝트 세팅

React 프로젝트를 Vite로 설정하는 방법은 다음과 같습니다. 이 과정에서 발생할 수 있는 문제와 해결 방법도 함께 설명드리겠습니다.

Vite 설치

Vite 글로벌 설치: 먼저, Vite를 글로벌로 설치합니다. 이를 위해 아래의 명령어를 사용합니다.

bash npm install -g create-vite

새로운 프로젝트 폴더 생성: 프로젝트를 위한 새로운 폴더를 생성하고 그 폴더로 이동합니다.

bash mkdir my-react-app cd my-react-app

React 앱 생성: Vite를 사용하여 새로운 React 애플리케이션을 생성합니다. 아래의 명령어를 입력합니다.

bash npm create vite@latest

이 때, 프로젝트의 템플릿으로 “React”를 선택합니다. TypeScript를 사용할 경우 “React + TypeScript”를 선택합니다.

종속성 설치

의존성 설치: 생성된 프로젝트의 폴더로 이동한 후, 필요한 패키지를 설치합니다.

bash npm install

개발 서버 실행: 아래의 명령어를 입력하여 개발 서버를 실행합니다.

bash npm run dev

이 명령어를 실행하면 기본적으로 http://localhost:5173/에서 개발 서버가 실행됩니다.

단계	명령어
Vite 설치	`npm install -g create-vite`
앱 생성	`npm create vite@latest`
의존성 설치	`npm install`
서버 실행	`npm run dev`

다른 내용도 보러가기 #1

React Vite에서 발생할 수 있는 오류

Vite를 사용하여 React 프로젝트를 설정하는 과정에서 여러 오류가 발생할 수 있습니다. 그 중에서도 가장 흔한 오류 두 가지를 살펴보겠습니다.

1. non-JS module files deprecated 오류

이 오류는 CSS나 이미지 파일과 같은 JavaScript가 아닌 모듈 파일의 처리와 관련이 있습니다. Vite의 버전이 2.x인 경우, 기본적으로 non-JavaScript 모듈을 지원하지 않기 때문에 발생합니다.

이러한 문제를 해결하기 위해서는 vite-plugin-react-pages와 같은 플러그인을 사용하여 해결할 수 있습니다.

해결 방법

아래의 명령어를 통해 vite-plugin-react-pages를 설치합니다.

bash npm install vite-plugin-react-pages

그 후, 프로젝트의 루트 디렉토리에 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-JS 모듈 파일을 JavaScript 파일로 직접 가져올 수 있게 되어, React 애플리케이션에서 non-JavaScript 모듈을 사용할 수 있습니다.

2. @vitejs/plugin-react 인스턴스 오류

다음으로 자주 발생하는 오류는 @vitejs/plugin-react 인스턴스를 찾을 수 없다는 것입니다. 이 오류는 Vite가 React 애플리케이션에서 MDX(Markdown + JSX) 파일을 지원하는 데 필요한 플러그인을 찾지 못했을 때 발생합니다.

해결 방법

아래의 명령어를 통해 @vitejs/plugin-react 플러그인을 설치합니다.

bash npm install @vitejs/plugin-react

그 다음, vite.config.js 파일을 수정하여 플러그인을 추가합니다.

“`javascript
import { defineConfig } from ‘vite’;
import react from ‘@vitejs/plugin-react’;

export default defineConfig({
plugins: [react()],
});
“`

이와 함께 MDX 파일을 사용하기 위해 추가적인 패키지와 Babel 플러그인도 설치해야 합니다. Babel 설정 파일인 .babelrc 또는 babel.config.js에 필요한 설정을 추가하여 오류를 해결할 수 있습니다.

오류 종류	해결 방법
non-JS module files deprecated	`vite-plugin-react-pages` 설치 및 설정
@vitejs/plugin-react 인스턴스 오류	`@vitejs/plugin-react` 설치 및 설정

프로젝트의 root 경로 설정

Vite를 사용할 때 index.html의 위치는 프로젝트의 root 디렉토리에 있어야 합니다. 이는 Vite가 index.html을 소스 코드의 일부로 간주하기 때문입니다.

CRA(Create React App)는 index.html을 public 폴더에 두지만, Vite는 root에 두는 방식을 채택하고 있습니다. 따라서 프로젝트 구조를 변경하여 index.html 파일을 root로 이동시켜야 합니다.

이러한 설정을 통해 Vite의 개발 서버가 정상적으로 작동하게 되며, SPA로 개발할 때 발생할 수 있는 여러 오류를 예방할 수 있습니다.

설정	Vite	CRA
index.html 위치	root 디렉토리	public 폴더
개발 서버 접근	`http://localhost:5173/`	`http://localhost:3000/`

결론

Vite를 사용하여 React 프로젝트를 설정하는 과정에서 발생할 수 있는 여러 오류와 그 해결 방법에 대해 살펴보았습니다. Vite는 빠른 개발 서버와 최적화된 빌드를 제공하여 개발자에게 많은 장점을 제공합니다.

하지만 초기 설정 과정에서 오류가 발생할 수 있으므로, 위에서 설명한 방법들을 통해 문제를 해결할 수 있습니다. React와 Vite의 조합은 현대적인 웹 애플리케이션 개발에 큰 도움이 될 것입니다.

개발자들은 이러한 도구를 활용하여 더욱 빠르고 효율적인 개발을 진행할 수 있습니다. Vite의 공식 문서와 다양한 커뮤니티 리소스를 참고하여 더욱 깊이 있는 이해를 쌓는 것도 좋은 방법입니다.

React npx 오류 해결 및 Vite 설치 방법 안내

Vite란 무엇인가?