리액트 프로젝트 초기 세팅은 성공적인 애플리케이션 개발의 첫 단추와 같습니다. 견고하고 일관된 개발 환경을 구축하는 것은 프로젝트의 확장성, 유지보수성, 그리고 협업 효율성을 결정짓는 매우 중요한 과정입니다.
많은 개발자가 처음 프로젝트를 시작할 때 어떤 도구를 선택하고 어떻게 설정해야 할지 막막함을 느끼곤 합니다. 과거에는 Create React App (CRA)이 표준처럼 여겨졌지만, 이제는 더 빠르고 유연한 Vite가 새로운 대세로 자리 잡았습니다.
이 글에서는 Vite를 기반으로 현대적인 리액트 프로젝트 초기 세팅 방법을 저의 경험을 바탕으로 상세하게 안내하고자 합니다. 코드 품질을 책임질 ESLint와 Prettier, 스타일링을 위한 styled-components, 그리고 상태 관리를 위한 Recoil까지, 실무에서 가장 많이 사용되는 조합으로 완벽한 개발 환경을 구축하는 모든 과정을 다루겠습니다.
✅ 프로젝트 생성 Vite 시작하기
과거의 표준이었던 CRA는 내부적으로 Webpack을 사용하여 다소 무겁고 개발 서버 구동 속도가 느리다는 단점이 있었습니다. 반면, Vite는 네이티브 ES 모듈(ESM)을 기반으로 하여 번들링 없이 소스 코드를 브라우저에 직접 제공함으로써 놀랍도록 빠른 개발 서버 속도를 자랑합니다.
Vite 프로젝트 생성
터미널을 열고 다음 명령어를 입력하여 간단하게 Vite 기반의 리액트 프로젝트를 생성할 수 있습니다.
여기서 my-react-app은 원하는 프로젝트 이름으로 변경하면 됩니다. --template react-ts 옵션을 사용하여 타입스크립트(TypeScript) 기반의 프로젝트를 생성하는 것을 강력히 권장합니다. 타입스크립트는 코드의 안정성과 가독성을 크게 향상시켜 대규모 프로젝트에서 발생할 수 있는 잠재적 오류를 사전에 방지해 줍니다.
프로젝트가 생성되었다면, 해당 폴더로 이동하여 필요한 패키지를 설치합니다.
이제 npm run dev 명령어를 실행하면 눈 깜짝할 사이에 개발 서버가 구동되는 것을 확인할 수 있습니다. 이것이 바로 Vite가 제공하는 압도적인 개발 경험의 시작입니다.
🧹 코드 품질 관리 ESLint와 Prettier 연동
일관된 코드 스타일과 잠재적인 오류를 사전에 방지하는 것은 협업의 기본입니다. ESLint는 코드 문법을 검사하고 버그를 찾는 린터(Linter)이며, Prettier는 정해진 규칙에 따라 코드 스타일을 자동으로 정리해 주는 코드 포맷터(Code Formatter)입니다. 이 둘을 함께 사용하면 팀원 모두가 동일한 스타일로 코드를 작성하게 되어 가독성과 유지보수성이 극대화됩니다.
필수 패키지 설치
먼저, ESLint와 Prettier 및 관련 플러그인들을 개발 의존성(devDependencies)으로 설치합니다.
설정 파일 생성
프로젝트 루트 디렉토리에 .eslintrc.cjs와 .prettierrc 파일을 생성하고 아래와 같이 내용을 작성합니다.
.eslintrc.cjs
.prettierrc
이 설정은 가장 보편적으로 사용되는 규칙들이며, 팀의 컨벤션에 맞게 자유롭게 수정할 수 있습니다. 완벽한 리액트 프로젝트 초기 세팅을 위해서는 이러한 코드 품질 도구의 통합이 필수적입니다.
🎨 스타일링 해결사 Styled-components
컴포넌트 기반 아키텍처에서 스타일 관리는 중요한 과제입니다. Styled-components는 CSS-in-JS 라이브러리로, JavaScript 코드 안에서 CSS를 작성하여 컴포넌트와 스타일을 하나로 묶어줍니다. 이를 통해 스타일의 스코프가 해당 컴포넌트로 한정되어 클래스 이름 충돌 문제를 원천적으로 방지하고, props를 활용한 동적 스타일링이 매우 용이해집니다.
설치 및 설정
Styled-components와 타입스크립트 지원을 위한 패키지를 설치합니다.
이제 컴포넌트 파일에서 styled-components를 import하여 바로 사용할 수 있습니다.
이렇게 작성된 스타일은 해당 컴포넌트에만 적용되므로 다른 컴포넌트의 스타일에 영향을 주지 않아 안정적인 스타일 관리가 가능합니다.
🧠 효율적인 상태 관리 Recoil
애플리케이션의 규모가 커지면 상태(State) 관리가 복잡해집니다. Redux나 MobX 같은 훌륭한 라이브러리들이 있지만, 상대적으로 설정이 복잡하고 보일러플레이트 코드가 많다는 단점이 있습니다. Recoil은 Facebook(현 Meta)에서 개발한 상태 관리 라이브러리로, 리액트의 내장 상태 관리 훅(hook)인 useState와 매우 유사한 사용법을 가지고 있어 학습 곡선이 낮고 직관적입니다.
Recoil 설정하기
먼저 Recoil 패키지를 설치합니다.
애플리케이션의 최상단(일반적으로 main.tsx 또는 App.tsx)을 RecoilRoot 컴포넌트로 감싸주어야 합니다.
main.tsx
Atom과 Selector 사용법
Recoil의 핵심 개념은 Atom과 Selector입니다.
예를 들어, 다크 모드 테마 상태를 관리하는 atom을 만들어 보겠습니다.
src/atoms/themeState.ts
이제 컴포넌트에서 useRecoilState 훅을 사용하여 이 상태를 읽고 업데이트할 수 있습니다.
이처럼 Recoil은 최소한의 코드로 간결하고 효율적인 전역 상태 관리를 가능하게 해줍니다. 리액트 프로젝트 초기 세팅 단계에서 상태 관리 전략을 결정하는 것은 매우 중요하며, Recoil은 훌륭한 선택지가 될 수 있습니다.
📂 깔끔한 경로 관리 절대 경로 설정
프로젝트 구조가 깊어질수록 ../../components/Button과 같은 상대 경로 지옥에 빠지기 쉽습니다. 이는 코드 가독성을 해치고 파일 위치를 변경할 때 유지보수를 어렵게 만듭니다. 절대 경로를 설정하면 @/components/Button처럼 프로젝트 루트를 기준으로 경로를 지정할 수 있어 훨씬 깔끔하고 직관적인 코드를 작성할 수 있습니다.
Vite와 TypeScript 설정
Vite 프로젝트에서는 vite.config.ts와 tsconfig.json 파일을 수정하여 절대 경로를 설정할 수 있습니다.
vite.config.ts
tsconfig.json
이제 프로젝트의 모든 파일에서 @/를 사용하여 src 폴더 내부의 파일과 폴더에 쉽게 접근할 수 있습니다. 이러한 작은 설정 하나가 개발 경험을 크게 향상시킵니다. 이로써 리액트 프로젝트 초기 세팅의 마지막 퍼즐이 맞춰졌습니다. 이 가이드를 통해 여러분의 다음 리액트 프로젝트가 더욱 견고하고 효율적으로 시작되기를 바랍니다.
관련 글
React TypeScript props 완벽 가이드 React.FC, interface, children 사용법
