파이썬 환경 설정부터 깃, 노드 버전 관리까지 무사히 거쳐 드디어 자바스크립트 진영의 가장 인기 있는 프론트엔드 라이브러리인 리액트(React)를 공부할 차례다. 공식 문서나 여러 개발 강의를 보면 가장 먼저 접하는 명령어가 바로 npx create-react-app my-app이다. 터미널에 이 한 줄을 당차게 치고 엔터를 누르면 리액트 프로젝트가 뚝딱 만들어질 것이라 기대하지만, 초보자들은 십중팔구 붉은색 에러 경고와 함께 멈춰버린 화면을 마주하게 된다.
npx: installed 99 in ...s 같은 메시지가 뜨다가 갑자기 패키지 설치가 거부되거나, 최신 버전의 노드와 충돌을 일으키며 프로젝트 생성 자체가 실패하는 현상은 초보 개발자를 가장 당혹스럽게 만드는 주범 중 하나다.
[소제목] 왜 create-react-app 실행 시 에러가 발생하는가
과거에는 리액트 입문용 프로젝트를 만들 때 위 명령어를 쓰는 것이 표준이었지만, 시간이 흐르면서 생태계에 큰 변화가 생겼다.
리액트 공식 팀은 더 이상
create-react-app패키지를 적극적으로 유지보수하지 않으며, 내부적으로 사용하는 의존성 패키지들이 최신 노드 버전과 충돌을 일으킨다.특히 전역에 구버전의
create-react-app이 캐시되어 남아있는 경우, 터미널은 새로운 패키지를 내려받지 못하고 꼬여버린 캐시를 참조하다가 에러를 뿜어낸다.따라서 무작정 예전 방식을 고집하기보다는, 현재 프론트엔드 생태계의 표준에 맞춘 대안을 이해하는 것이 현명하다.
[소제목] 에러를 피하고 안전하게 리액트 프로젝트를 시작하는 방법
만약 기존 방식으로 인해 계속 에러가 발생한다면, 전역에 남은 찌꺼기 패키지를 깔끔하게 지우거나 최신 권장 도구를 사용하는 것이 정답이다. 직접 겪어본 바에 따르면 원인 모를 충돌로 시간을 낭비하느니 최신 도구인 Vite(비트)로 넘어가거나 캐시를 비우는 편이 훨씬 빠르다.
기존에 잘못 설치된 패키지 캐시를 완전히 무시하고 최신 버전을 강제로 실행하려면 다음 명령어를 시도해 볼 수 있다. npx clear-npx-cache
그후 아래와 같이 최신 패키지 버전을 명시하여 생성한다. npx create-react-app@latest my-app
하지만 최근 실무와 커뮤니티에서는 속도가 훨씬 빠르고 가벼운 빌드 도구인 Vite를 이용해 리액트 환경을 구축하는 것을 강력하게 권장한다. npm create vite@latest my-app -- --template react
Vite를 이용해 프로젝트를 만들면 몇 초 만에 파일들이 생성되며, 이후 생성된 폴더로 들어가 npm install과 npm run dev를 입력하는 것만으로 훨씬 쾌적한 개발 서버를 띄울 수 있다.
[소제목] 프로젝트 생성 후 반드시 점검해야 할 초기 파일 구조
어떤 방식으로든 리액트 프로젝트를 무사히 생성했다면, VS Code에서 해당 폴더를 열어 파일 구조를 눈으로 직접 확인해야 한다.
node_modules: 프로젝트에 필요한 수많은 라이브러리가 들어있는 거대한 폴더로, 용량이 매우 크기 때문에 절대 깃허브에 올리면 안 된다.src: 우리가 앞으로 컴포넌트를 만들고 코드를 작성할 메인 작업 공간이다.package.json: 이 프로젝트가 사용하는 라이브러리 목록과 실행 스크립트가 정의된 설계도다.
프로젝트를 처음 열었다면 터미널에 npm run start (또는 Vite의 경우 npm run dev)를 입력하여 브라우저에 리액트 기본 로고 화면이 정상적으로 뜨는지 눈으로 검증하는 과정이 필수적이다.
[소제목] 초보자가 자주 하는 실수와 주의사항
프로젝트 폴더 이름을 지을 때 흔히 저지르는 실수는 한글이나 대문자, 혹은 띄어쓰기를 포함하는 것이다. 예를 들어 내 리액트 프로젝트나 My-App처럼 만들면 나중에 패키지를 빌드하거나 연동할 때 알 수 없는 경로 에러의 원인이 된다. 폴더 이름은 항상 영문 소문자와 하이픈(-) 조합으로 간결하게 짓는 습관을 들여야 한다.
또한, 엉뚱한 폴더 위치에서 프로젝트 생성 명령어를 쳐서 기존 프로젝트 내부에 또 다른 리액트 프로젝트가 겹쳐서 생성되는 대참사도 주의해야 한다. 항상 터미널의 현재 경로(pwd 또는 디렉토리 위치)를 정확히 확인하고 명령을 실행하는 태도가 필요하다. 처음에는 툴의 변화나 에러 때문에 당황스럽겠지만, 이 과정을 통해 프론트엔드 빌드 도구의 흐름을 자연스럽게 이해할 수 있게 된다.
핵심 요약:
create-react-app명령어는 오래되거나 버전 충돌을 일으키기 쉬우므로 최신 대안인 Vite 등을 고려해야 한다.프로젝트 폴더 이름은 반드시 영문 소문자와 하이픈 위주로 간결하게 지어야 경로 에러를 예방할 수 있다.
프로젝트 생성 후에는
npm install과 실행 명령어를 통해 브라우저에서 초기 화면이 잘 뜨는지 직접 검증해야 한다.
다음 편 예고: 다음 편에서는 HTML과 CSS 기본 레이아웃 작업 시 반드시 알아야 할 박스 모델(Box-Model)의 이해와 실무 팁을 알아본다.
이 글을 읽으면서 리액트 프로젝트를 세팅하다가 에러를 겪었거나 도구 선택에서 고민했던 경험이 있다면 댓글로 편하게 공유해 주세요!
0 댓글