리액트 설치부터 시작하는 SNS 만들기 프로젝트 1편이다. 이 글에서는 React 프로젝트를 새로 만들고 실행하기까지의 전 과정을 다룬다. 프로젝트 폴더 생성 → 리액트 설치 → 필요한 dependencies 설치 → 개발 서버 실행 → 폴더 구조와 추가 설정 순서로 정리하고, 설치 중 마주친 Node.js 버전 오류와 해결 방법도 함께 기록한다. React를 처음 세팅하는 사람도 그대로 따라 할 수 있도록 명령어 중심으로 구성했다.
프로젝트 개요
이 프로젝트의 목표는 React로 SNS(소셜 네트워크 서비스) 클론을 만들어 보는 것이다. 1편의 범위는 화면·기능 구현이 아니라, 그 토대가 되는 React 개발 환경 구축이다. 빈 폴더에서 시작해 React를 설치하고, 라우팅·상태관리·폼 처리에 필요한 패키지를 한 번에 깔아 둔 뒤, 개발 서버가 정상적으로 뜨는 것까지 확인한다.
이번 편에서 설치할 핵심 패키지는 다음과 같다.
- react-router-dom — 페이지 라우팅
- redux · react-redux · redux-thunk — 전역 상태관리와 비동기 처리
- formik · yup — 폼 상태관리와 입력값 검증
- react-icons — 아이콘
사전 준비 — Node.js와 npm
리액트 설치는 npm(Node Package Manager)을 통해 이뤄지므로, 먼저 Node.js가 설치돼 있어야 한다. Node.js를 설치하면 npm도 함께 설치된다. 설치 여부와 버전은 아래 명령으로 확인한다.
node --version
npm --version버전이 정상적으로 출력되지 않으면 Node.js 공식 사이트에서 LTS 버전을 내려받아 설치한다. 뒤에서 다루겠지만, 최신 npm은 일정 버전 이상의 Node.js를 요구하므로 가급적 최신 LTS를 쓰는 편이 오류를 피하기 좋다.
프로젝트 폴더 생성
먼저 프로젝트를 담을 폴더를 만든다.
mkdir myApp리액트 설치
생성한 폴더로 들어가 리액트를 설치한다. 이번 프로젝트에서는 Create React App 계열로 프로젝트를 만들고, npm init으로 package.json을 초기화했다.
npm install -g create-react myApp
npm init설치가 완료되면 프로젝트 폴더에 node_modules, package.json, package-lock.json 등의 파일과 디렉터리가 생성된다.
오류 노트 — package.json 미생성
설치 과정에서 package.json 파일이 자동으로 만들어지지 않았다. 이 경우 npm init을 실행해 직접 package.json을 생성·설정해 주면 된다. 질문에 모두 엔터로 넘기려면 npm init -y로 기본값 파일을 바로 만들 수도 있다.
필요한 dependencies 설치
리액트 설치가 끝나면 프로젝트에 필요한 dependencies를 한 번에 설치한다.
npm i formik yup react-icons redux redux-thunk react-redux react-router-dom각 패키지의 역할은 다음과 같다.
| 패키지 | 역할 |
|---|---|
| react-router-dom | URL 기반 페이지 라우팅(화면 전환) |
| redux | 애플리케이션 전역 상태 저장소 |
| react-redux | React 컴포넌트와 Redux 스토어 연결 |
| redux-thunk | 비동기 액션(예: API 호출) 처리 미들웨어 |
| formik | 폼 상태관리(입력값·제출·에러) |
| yup | 폼 입력값 스키마 검증(Formik과 연동) |
| react-icons | 인기 아이콘 세트 컴포넌트 제공 |
설치가 끝나면 package.json의 dependencies 항목에 위 패키지들이 버전과 함께 추가된 것을 확인할 수 있다.
개발 서버 실행
설치가 모두 끝나면 개발 서버를 실행한다.
npm start정상적으로 실행되면 개발 서버가 뜨고 브라우저에서 http://localhost:3000 주소로 React 앱을 확인할 수 있다.
오류 노트 — Node.js 버전 불일치
npm start 단계에서 무한 렌더링이 걸리며 정상 동작하지 않았다. 원인은 설치된 npm 버전이 요구하는 Node.js 버전과 실제 Node.js 버전이 맞지 않은 것이었다. npm --version 실행 시 아래와 같은 오류가 출력됐다.
PS C:Usersske40myapp> npm --version
ERROR: npm v10.2.5 is known not to run on Node.js v14.15.1. This version of npm supports the following node versions: ^18.17.0 || >=20.5.0. You can find the latest version at https://nodejs.org/.해결은 npm과 Node.js의 버전을 서로 맞추는 것이었다. npm을 최신으로 올리고, Node.js도 최신 버전으로 다시 설치해 버전을 일치시켰더니 정상 작동했다.
npm install -g npm@latest위 오류 메시지처럼 npm v10대는 Node.js 18.17 이상(또는 20.5 이상)을 요구한다. npm start가 멈추거나 알 수 없는 오류가 난다면, 가장 먼저 node --version과 npm --version으로 버전 호환을 점검하는 것이 좋다.
폴더 구조와 추가 설정
실행을 마친 뒤 개발 편의를 위해 추가로 설정한 부분과, 프로젝트에서 직접 만든 파일들을 정리한다.
VS Code 확장 — ES7+ React/Redux/React-Native snippets
컴포넌트를 빠르게 생성하기 위해 ES7+ React/Redux/React-Native snippets 확장(v4)을 설치했다. 에디터에서 아래 단축어를 입력하면 컴포넌트 골격이 자동 생성된다.
rce: class component 생성rafce: arrow function component 생성rfce: function component 생성
babel plugin 설치
빌드 과정에서 필요한 babel plugin을 개발 의존성으로 추가했다.
npm install --save-dev @babel/plugin-proposal-private-property-i생성한 폴더와 파일
SNS 화면을 구성하기 위해 다음과 같은 컴포넌트·파일을 만들었다. 실제 구현은 다음 편에서 다룬다.
- Sidebar.jsx — 좌측 사이드바
- HomePage.jsx — 홈(메인) 페이지
- Router.jsx — 라우팅 정의(react-router-dom)
- App.js — 최상위 컴포넌트
여기까지 설정하면 빈 화면이지만 라우팅과 기본 레이아웃이 동작하는 상태의 React 앱이 준비된다.
참고 — Create React App은 더 이상 권장되지 않는다
이 글은 Create React App(CRA) 기반으로 진행했지만, 새로 시작한다면 알아 둘 점이 있다. React 팀은 2025년 2월 14일자로 Create React App을 공식 deprecated(지원 종료) 처리했다. 이제 새 프로젝트에는 CRA 대신 프레임워크나 최신 빌드 도구를 쓰도록 권장한다.
- 프레임워크: Next.js, React Router, Expo
- 빌드 도구(SPA·커스텀 환경): Vite, Parcel, Rsbuild
단순한 SPA(단일 페이지 앱)를 빠르게 띄우려는 목적이라면 보통 Vite를 가장 많이 쓴다. 아래처럼 한 줄로 프로젝트를 만들 수 있고, 빌드·개발 서버 속도가 CRA보다 빠르다.
npm create vite@latest myApp -- --template react
cd myApp
npm install
npm run dev이 시리즈는 작성 당시 CRA로 진행한 기록을 그대로 남기되, 지금 새로 따라 한다면 위와 같이 Vite로 환경을 잡는 것을 권한다. 패키지 설치(npm i ...)와 컴포넌트 구성 방식은 빌드 도구와 무관하게 동일하게 적용된다.
다음 편 예고
다음 편에서는 이렇게 준비한 프로젝트 위에서 SNS의 화면과 기능을 실제로 구현한다. 사이드바·홈 화면 레이아웃을 잡고, react-router-dom으로 페이지를 연결하며, redux로 상태를 관리하는 흐름을 단계별로 다룰 예정이다.
정리
지금까지 SNS 만들기 프로젝트의 첫 단계로 리액트 설치와 개발 환경 구성을 마쳤다. 핵심 순서는 폴더 생성 → 리액트 설치(+ package.json 초기화) → dependencies 설치 → 개발 서버 실행 → 폴더 구조·추가 설정이다. npm start가 멈출 때는 Node.js와 npm의 버전 호환을 먼저 확인하면 대부분 해결된다. 새로 시작하는 경우라면 CRA 대신 Vite로 환경을 잡는 것을 권한다. 다음 편에서 본격적으로 화면과 기능을 만들어 보자.
💬 댓글 0