Wiki_FE_BASIC

프론트엔드 개발 온보딩 가이드

React 개발에 투입되기 전, 반드시 숙지해야 할 핵심 기초 개념을 정리한 문서입니다.
대상 독자: 웹 프론트엔드 개발 경험이 없는 신입 개발자

---

목차

1. 웹의 3요소: HTML / CSS / JS
2. Node.js와 npm이란?
3. 프로젝트 구조
4. 핵심 파일 설명
5. pnpm이란?
6. 자주 쓰는 CLI 명령어 요약

---

1. 웹의 3요소: HTML / CSS / JS

브라우저가 화면에 콘텐츠를 표시하는 방식은 세 가지 언어의 역할 분리에 기반합니다.

언어	역할	비유
HTML	구조 (Structure)	건물의 골조
CSS	스타일 (Style)	건물의 인테리어
JavaScript (JS)	동작 (Behavior)	건물의 전기·자동문

HTML (HyperText Markup Language)

페이지의 콘텐츠와 구조를 정의합니다. 태그(Tag)라는 단위로 요소를 표현합니다.

<!DOCTYPE html>
<html lang="ko">
  <head>
    <meta charset="UTF-8" />
    <title>페이지 제목</title>
  </head>
  <body>
    <h1>제목</h1>
    <p>단락 텍스트</p>
    <button>클릭</button>
  </body>
</html>

CSS (Cascading Style Sheets)

HTML 요소의 시각적 표현을 정의합니다. 색상, 크기, 배치, 애니메이션 등을 담당합니다.

h1 {
  color: #333;
  font-size: 24px;
}

button {
  background-color: #0070f3;
  color: white;
  padding: 8px 16px;
  border-radius: 4px;
}

JavaScript (JS)

페이지의 동적 동작을 구현합니다. 사용자 이벤트 처리, 데이터 통신(API 호출), DOM 조작 등을 담당합니다.

const button = document.querySelector('button');

button.addEventListener('click', () => {
  alert('버튼이 클릭되었습니다.');
});

React는 JS를 기반으로 동작합니다. HTML, CSS, JS의 기본 개념을 이해한 상태에서 React를 학습해야 합니다.

---

2. Node.js와 npm이란?

Node.js

JavaScript는 원래 브라우저 안에서만 실행되는 언어였습니다.
Node.js는 JS를 브라우저 밖, 즉 서버나 로컬 환경에서도 실행할 수 있게 해주는 런타임(Runtime)입니다.

React 개발 환경을 구성하고, 빌드 도구를 실행하고, 패키지를 설치하는 모든 작업이 Node.js 위에서 동작합니다.

브라우저  →  JS 실행 가능 (원래부터)
로컬 PC  →  Node.js 설치 시 JS 실행 가능

npm (Node Package Manager)

npm은 Node.js와 함께 설치되는 패키지 관리 도구입니다.
오픈소스 라이브러리(패키지)를 설치·관리·삭제하는 데 사용합니다.

# React 프로젝트 생성 예시
npm create vite@latest my-app

# 패키지 설치
npm install axios

# 개발 서버 실행
npm run dev

**패키지(Package)**란, 다른 개발자들이 만들어 공개한 재사용 가능한 코드 묶음입니다.
npm을 통해 수십만 개의 패키지를 무료로 가져와 사용할 수 있습니다.

---

3. 프로젝트 구조

React 프로젝트(Vite 기준)의 전형적인 디렉토리 구조는 다음과 같습니다.

my-app/
├── node_modules/        # 설치된 패키지들이 저장되는 폴더 (직접 수정 금지)
├── public/              # 정적 파일 (favicon, 이미지 등)
│   └── favicon.ico
├── src/                 # 실제 소스 코드 작성 공간
│   ├── assets/          # 이미지, 폰트 등 정적 자원
│   ├── components/      # 재사용 가능한 UI 컴포넌트
│   │   └── Button.jsx
│   ├── pages/           # 라우트(페이지) 단위 컴포넌트
│   │   └── Home.jsx
│   ├── App.jsx          # 최상위 루트 컴포넌트
│   └── main.jsx         # 애플리케이션 진입점(Entry Point)
├── .gitignore           # Git에서 제외할 파일/폴더 목록
├── index.html           # HTML 템플릿 (브라우저가 처음 로드하는 파일)
├── package.json         # 프로젝트 메타데이터 및 의존성 정의
├── package-lock.json    # 패키지 버전을 고정하는 잠금 파일 (npm 전용)
└── vite.config.js       # 빌드 도구(Vite) 설정 파일

각 폴더의 역할 요약

경로	설명
node_modules/	npm으로 설치한 패키지들의 실제 파일. 절대 직접 수정하지 않습니다.
public/	빌드 과정 없이 그대로 제공되는 정적 파일.
src/	개발자가 작성하는 모든 소스 코드. 대부분의 작업이 이 안에서 이루어집니다.
src/components/	버튼, 헤더 등 여러 페이지에서 재사용되는 UI 단위.
src/pages/	URL 경로에 대응하는 페이지 단위 컴포넌트.

node_modules/ 폴더는 용량이 매우 크므로 Git에 올리지 않습니다.
.gitignore 파일에 node_modules가 명시되어 있는지 반드시 확인하십시오.

---

4. 핵심 파일 설명

package.json

프로젝트의 신분증이자 설계도에 해당하는 파일입니다. 프로젝트 이름, 버전, 사용 중인 패키지 목록, 실행 가능한 명령어 등을 정의합니다.

{
  "name": "my-app",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "vite": "^5.0.0",
    "@vitejs/plugin-react": "^4.0.0"
  }
}

필드	설명
scripts	npm run <명령어>로 실행할 수 있는 단축 명령어 정의
dependencies	프로덕션(실제 서비스)에 필요한 패키지 목록
devDependencies	개발 환경에서만 필요한 패키지 목록 (빌드 도구, 린터 등)

package-lock.json / pnpm-lock.yaml

패키지의 정확한 버전과 의존 관계를 고정하는 잠금 파일(Lock File)입니다.
팀원 간 동일한 환경을 보장하기 위해 반드시 Git에 커밋해야 합니다.

패키지 매니저	잠금 파일 이름
npm	package-lock.json
pnpm	pnpm-lock.yaml
yarn	yarn.lock

잠금 파일은 직접 수정하지 않습니다. 패키지 설치·삭제 시 자동으로 갱신됩니다.

index.html

브라우저가 가장 먼저 로드하는 HTML 파일입니다.
React 앱 전체가 이 파일 안의 단일 <div> 요소에 마운트(Mount)됩니다.

<!DOCTYPE html>
<html lang="ko">
  <head>
    <meta charset="UTF-8" />
    <title>My App</title>
  </head>
  <body>
    <!-- React 앱이 이 div 안에 렌더링됩니다 -->
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

src/main.jsx

**애플리케이션의 진입점(Entry Point)**입니다. React가 index.html의 #root 요소에 연결되는 지점입니다.

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.jsx';

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

.gitignore

Git 버전 관리에서 제외할 파일과 폴더를 명시하는 파일입니다.

# 의존성 폴더
node_modules/

# 빌드 결과물
dist/

# 환경 변수 파일 (비밀 키 등 민감 정보 포함)
.env
.env.local

---

5. pnpm이란?

**pnpm(Performant npm)**은 npm의 대안 패키지 매니저입니다.
npm과 동일한 역할을 하지만, 속도와 디스크 효율 면에서 우수합니다.

npm과 pnpm의 차이

항목	npm	pnpm
설치 속도	보통	빠름
디스크 사용량	프로젝트마다 패키지 복사	전역 저장소에 1회 저장 후 링크 공유
잠금 파일	package-lock.json	pnpm-lock.yaml
명령어 체계	npm install / npm run	pnpm install / pnpm run (거의 동일)

pnpm 설치

# npm을 통해 pnpm 전역 설치
npm install -g pnpm

# 설치 확인
pnpm --version

pnpm 기본 명령어

# package.json에 명시된 모든 패키지 설치
pnpm install

# 새 패키지 추가 (dependencies)
pnpm add axios

# 개발용 패키지 추가 (devDependencies)
pnpm add -D eslint

# 패키지 제거
pnpm remove axios

# 스크립트 실행
pnpm run dev
pnpm dev          # run 생략 가능

사내 프로젝트가 pnpm을 사용 중이라면, npm install 대신 반드시 pnpm install을 사용하십시오.
매니저를 혼용하면 잠금 파일이 충돌하여 의존성 문제가 발생할 수 있습니다.

---

6. 자주 쓰는 CLI 명령어 요약

신규 프로젝트 합류 시 가장 먼저 실행하는 명령어 순서입니다.

# 1. 저장소 클론
git clone <저장소 URL>
cd <프로젝트 폴더>

# 2. 의존성 설치 (package.json 기준으로 패키지 일괄 설치)
pnpm install      # pnpm 사용 시
# 또는
npm install       # npm 사용 시

# 3. 개발 서버 실행
pnpm dev

# 4. 브라우저에서 확인
# → http://localhost:5173 (Vite 기본값)

명령어	설명
pnpm install	패키지 설치 (최초 1회, 또는 패키지 변경 후)
pnpm dev	개발 서버 실행 (코드 변경 시 자동 새로고침)
pnpm build	프로덕션용 빌드 파일 생성 (dist/ 폴더)
pnpm add <패키지명>	새 패키지 설치
pnpm remove <패키지명>	패키지 제거

---

참고 자료

• [Node.js 공식 문서](https://nodejs.org/ko)
• [npm 공식 문서](https://docs.npmjs.com)
• [pnpm 공식 문서](https://pnpm.io/ko)
• [Vite 공식 문서](https://ko.vitejs.dev)
• [React 공식 문서](https://ko.react.dev)