React 개발 환경 구성

Node.js 설치

Node.js가 PC에 설치되어 있지 않다면 설치한다. LTS버전(v22.20.0)을 설치합니다.

온라인 설치
- 설치링크:(https://nodejs.org)
오프라인 설치
- node.js설치 파일을 파일서버에서 제공하므로 /aaaa/bbbbb/Frontend 위치에서 다운로드 받아 설치 합니다.
- node.js설치 파일: node-v24.14.1-win-x64.zip
  - zip를 통해 설치할 경우 압축을 풀면 다음과 같은 폴더 구조를 가집니다. 여기서 node.exe 를 실행하면 됩니다.
```
node-v24.x.x-win-x64/
├── node.exe          ← Node.js 실행 파일
├── npm.cmd           ← npm 명령어
├── npx.cmd
├── node_modules/
│   └── npm/
└── ...
```
- 또는 node-v24.14.1-x64.msi 설치 파일을 통해 설치 진행합니다.
  - msi를 통해 설치 중 "Automatically install the necessary tools" 옵션을 체크하면 Chocolatey, Python, Visual Studio Build Tools 등을 인터넷에서 추가 다운로드하려 합니다. 오프라인 환경이라면 이 옵션은 반드시 체크 해제해야 합니다.

LTS버전 (v24.14.1) - 설치 완료 후 아래와 같이 윈도우 명령 프롬프트 창에서 node와 npm 설치 여부를 확인해봅니다.

# 설치 후 설치 버전 확인
node -v
# 24.14.1 

npm -v
# 11.9.0

Git 설치

Git사용을 위하여 설치합니다.
설치링크:(https://git-scm.com/downloads)

오프라인 설치
- Git 설치 파일을 파일서버에서 제공하므로 /aaaa/bbbbb/Frontend 위치에서 다운로드 받아 설치 합니다.
- Git 설치 파일 : Git-2.53.0.2-64-bit.exe

pnpm workspaces 설치 (필요시에만)

모노레포 구조의 마이크로 프론트엔드 프로젝트 환경에서 각 업무(remote app)영역을 독립적으로 개발하고 배포할 수 있게 해주는 도구입니다.
- 상황에 따라 멀티레포 환경의 각 remote 앱 내부에서 하이브리드 형태의 모노레포 구조를 사용할 때 필요할 수 있습니다.

pnpm workspaces란?

pnpm workspaces는 하나의 코드 저장소(Repository) 안에서 여러 개의 독립적인 프로젝트(패키지)를 효율적으로 관리할 수 있게 해주는 도구입니다.

일반적인 프로젝트라면 각 폴더마다 node_modules가 생기고 중복된 라이브러리가 설치되겠지만, pnpm은 이를 하나로 묶어 관리하면서도 각 프로젝트가 독립성을 유지하게 돕습니다.

pnpm Workspaces와 함께 모노레포에 도움이 되는 도구들

Lerna: Lerna: https://github.com/lerna/lerna
Nx: Nx: https://nx.dev/
Turborepo: Turborepo: https://turbo.build/
Pnpm: Pnpm: https://pnpm.io/
Yarn: Yarn: https://yarnpkg.com/
Bun: Bun: https://bun.sh/
npm: npm: https://www.npmjs.com/

1. pnpm 온라인 설치

먼저 pnpm을 사용하기 위하여 전역으로 설치합니다.

# npm을 통한 설치
npm install -g pnpm

# 또는 standalone 설치 (권장)
curl -fsSL https://get.pnpm.io/install.sh | sh -

# 설치 확인
pnpm --version

만약 위와같이 pnpm을 설치했는데 pnpm 명령어가 실행이 되지않고 오류가 발생한다면, PATH에 npm 경로가 등록 되어있지 않았을 수도 있습니다. 따라서 다음과 같이 PATH에 npm 경로를 등록합니다.
- 1. 시스템 환경 변수 열기
- 2. Win + R → sysdm.cpl 입력 → Enter, 또는: 설정 → 시스템 → 정보 → 고급 시스템 설정
- 3. 환경 변수 버튼 클릭
- 4. 사용자 변수에서 Path 선택 → 편집
- 5. 새로 만들기 → C:\Users\PC_NIC\AppData\Roaming\npm 입력 → 확인 (개인마다 npm 경로가 다를 수 있으니 확인하고 입력합니다.)
- 6. 열려 있는 터미널/VS Code/Cursor를 모두 닫았다가 다시 열기
- 7. 새 터미널에서 pnpm -v 실행해 확인

2. pnpm 오프라인 설치

1. pnpm 설치

# pnpm-win-x64.exe를 원하는 경로에 복사 후 PATH 등록
# 예: C:\pnpm\pnpm.exe 로 복사하고 환경변수 PATH에 C:\pnpm 추가

2. store 복사

# 온라인 PC와 동일한 경로에 store 폴더 붙여넣기
# 예: C:\Users\사용자명\AppData\Local\pnpm\store

3. 오프라인으로 패키지 설치

# cd 프로젝트_루트
# pnpm install --offline

store 경로가 다를 경우

pnpm install --offline --store-dir C:\복사한\store\경로

Visual Studio Code 설치

Vue Frontend 개발을 위한 Microsoft사에서 만든 개발용 코드 편집기입니다.

온라인 설치
- 설치링크:(https://code.visualstudio.com/Download)
오프라인 설치
- Visual Studio Code 설치 파일을 파일서버에서 제공하므로 /aaaa/bbbbb/Frontend 위치에서 다운로드 받아 설치 합니다.
- Visual Studio Code 설치 파일 : VSCodeUserSetup-x64-1.114.0.exe
- 오프라인이면 .vscode/settings.json 파일 생성 및 외부 연결 시도 막는 부분 세팅
```
{
  "update.mode": "none",
  "telemetry.telemetryLevel": "off",
  "extensions.autoUpdate": false,
  "extensions.autoCheckUpdates": false
}
```
Visual Studio Code(VSCode) 를 설치한 후 개발에 도움이 되는 Extensions를 설치합니다.

VSCode Extensions 설치

VSCode에서 사용할 수 있는 필수 또는 선택 익스텐션 입니다.

ESLint : (필수) 코드의 포맷팅과 품질관리 도구.
Prettier - Code formatter : (필수) 코드를 정렬해주는 Formatter.
GitLens Git supercharged : (필수) 각 파일에서 Line별로 가장 마지막에 누가, 언제, 무슨 commit했는 지 확인할 수 있다.
Git Graph : (선택) Git 저장소의 Git Graph를 보고 Git 작업을 수행합니다.
indent-rainbow : (선택) 들여쓰기에 컬러표시로 가독성을 좋게함.
Import Cost (Display import/require package size in the editor) : (선택) import하는 모듈의 사이즈를 보여줌.
TODO Highlight : (선택) 주석처리 시 'TODO:' 이렇게 시작하는 text를 입력하면 색깔로 반전시켜주는 기능.
vscode-icons : (선택) VSCode의 아이콘을 이쁘게 보여줌.
es6-string-html : (선택) es6 여러 줄 문자열에서 구문 강조 표시.
Tailwind CSS IntelliSense : (선택) Tailwindcss 를 사용하는 프로젝트에서 도움이 되는 익스텐션입니다.
SVN : (SVN을 사용하는 환경이라면...) 검색된 svn중에 Integrated Subversion source control Chris Johnston을 설치한다.
MDX (unified unifiedjs.com) : (선택)(Language support for MDX) MDX 파일 내 JSX 문법에 대해 기본적인 하이라이팅과 일부 오류 감지.

VSCode Extensions 온라인 설치 방법

VSCode에서 아래 이미지와 같이 검색어 입력란에 Extensions명을 입력하여 설치합니다.

VSCode Extensions 오프라인 VSIX설치 방법(외부 인터넷이 되지 않는 환경일때 )

외부 인터넷이 되지 않는 환경의 PC에서는 따로 제공하는 *.vsix파일을 이용하여 설치합니다.
아래와 같이 순서대로 가지고 있는 *.vsix파일을 선택하고 install합니다.
설치가 완료 되고 오른쪽 하단에 아래와 같이 팝업이 뜨면 성공.

Cursor 설치 (선택)

만약 Cursor를 사용한다면 VSCode와 거의 유사해서 문제없이 사용 가능합니다.

Cursor 설치 링크
Cursor설치 후 우측 메뉴를 좌측으로 이동을 원할 때 다음과 같이 해당 값을 비활성화 합니다.

Chrome Browser 설치

Frontend 개발 시 로컬환경에서 다양한 개발자 환경을 제공하는 크롬 브라우저를 설치합니다.

온라인 설치
- Chrome 브라우저 설치 링크
오프라인 설치
- Chrome 브라우저 설치 파일을 파일서버에서 제공하므로 /aaaa/bbbbb/Frontend 위치에서 다운로드 받아 설치 합니다.
- Chrome 브라우저 설치 파일 : GoogleChromeStandaloneEnterprise64.msi

React Developer Tools 설치 (크롬 브라우저 확장 프로그램)

React를 사용할 때, React 앱을 보다 더 사용자 친화적인 인터페이스에서 검사하고 디버깅할 수 있습니다.

온라인 설치
- React Developer Tools 설치 링크
오프라인 설치
- Chrome Extensions 오프라인 .crx설치 방법#
  - crx파일이 있으면 chrome브라우저에서 chrome://extensions를 입력하고 해당 브라우저에 crx파일을 드래그앤드롭하면 extension설치가 된다.

Redux DevTools 설치 (크롬 브라우저 확장 프로그램)(필요시에만)

React에서 사용하는 상태 관리 라이브러리 Redux의 상태 변경을 디버깅 할 수 있는 Redux DevTools를 설치합니다.
Redux DevTools 설치 링크

오프라인 설치
- Chrome Extensions 오프라인 .crx설치 방법#
  - crx파일이 있으면 chrome브라우저에서 chrome://extensions를 입력하고 해당 브라우저에 crx파일을 드래그앤드롭하면 extension설치가 된다.

TanStack Query(React Query) DevTools 설치 (크롬 브라우저 확장 프로그램)(필요시에만)

React에서 사용하는 상태 관리 라이브러리 TanStack Query의 상태 변경을 디버깅 할 수 있는 TanStack Query DevTools를 설치합니다.
TanStack Query(React Query) DevTools 설치 링크

TanStack Query(React Query) 외에도 Zustand도 함께 고려해볼 필요가 있습니다.
오프라인 설치
- Chrome Extensions 오프라인 .crx설치 방법#
  - crx파일이 있으면 chrome브라우저에서 chrome://extensions를 입력하고 해당 브라우저에 crx파일을 드래그앤드롭하면 extension설치가 된다.

VSCode에서 Git bash 쉘(Shll)프로그램을 사용하자.

VSCode를 사용하여 Frontend 개발을 진행하다 보면 터미널창을 이용하는 상황이 많이 생깁니다.
만약 Windows(윈도우) 운영체제(OS)를 사용하는 환경 이라면, 리눅스 커맨드를 사용할 수 있는 Git bash 터미널을 사용합니다.
VSCode에서 터미널창을 열때 아래와 같이 Git bash로 바꿔서 사용합니다.

Visual Studio Code (VSCode) 코드편집기 설정

.vscode/settings.json 파일은 Frontend 코드를 Git 레포지토리에서 내려받으면 기본으로 세팅되어 있습니다.
만약 코드를 내려받은 후 .vscode/settings.json 파일이 없다면, 다음과 같이 생성합니다.

settings.json 셋팅 (VSCode 설정)

Frontend (React) 개발을 위해 VSCode를 활용할 것입니다. 따라서 개발자의 통일된 코드 작성을 위하여 VSCode의 환경설정을 settings.json파일에 적용합니다.

settings.json 설정

settings.json 파일열기 : f1 ⤍ settings 입력 ⤍ Preferences: Open Workspace Settings (JSON) 클릭.
위와같이 열면 프로젝트 루트에 .vscode 디렉토리가 생성되고 settings.json파일이 생성됩니다.

settings(설정)가 적용되는 우선 순위 : .vscode settings.json ⤇ settings.json ⤇ defaultSetting.json(수정하지 않는 파일.)
defaultSetting.json은 모든 설정내용이 다 들어있는 기본 설정 파일입니다. 수정은 하지 않는 파일입니다.

.vscode 디렉토리에 생성된 settings.json 파일에 아래 내용 입력합니다.

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "editor.tabSize": 2,
  "editor.detectIndentation": false,
  "editor.insertSpaces": false,
  "editor.renderWhitespace": "all",
  "editor.comments.insertSpace": false,
  "files.associations": {
    "*.json": "jsonc"
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],
  "eslint.workingDirectories": [{ "mode": "auto" }],
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "eslint.useFlatConfig": true,
  "css.lint.unknownAtRules": "ignore",
  "scss.lint.unknownAtRules": "ignore",
  "less.lint.unknownAtRules": "ignore",
  "[markdown]": {
    "editor.formatOnSave": false,
    "editor.codeActionsOnSave": {
      "source.fixAll.eslint": "never"
    }
  },
  "[mdx]": {
    "editor.formatOnSave": false,
    "editor.defaultFormatter": null
  },
  "update.mode": "none",
  "telemetry.telemetryLevel": "off",
  "extensions.autoUpdate": false,
  "extensions.autoCheckUpdates": false
}

⭐ 이렇게 settings.json 파일로 VSCode 설정을 하면 메뉴(File ⤍ Preferences ⤍ Settings) 로 설정한것 보다 우선순위가 높게 적용됩니다.

설명

"editor.formatOnSave" : 파일 저장 시 자동으로 코드 서식을 정리합니다.
"editor.codeActionsOnSave" ⤍ "source.fixAll.eslint" : 파일 저장 시 ESLint가 감지한 모든 문제를 자동으로 수정합니다.
"editor.tabSize" : 탭 크기를 몇칸으로 설정할지 지정합니다.
"editor.detectIndentation" : VSCode가 파일의 들여쓰기를 자동으로 감지하는 기능을 활용할지 여부 입니다.
"editor.insertSpaces" : 탭 키를 누를 때 공백 대신 탭 문자를 삽입합니다.
"editor.renderWhitespace" : 공백 문자를 시각적으로 표시합니다.
"editor.comments.insertSpace" : 주석 기호(//, /*) 뒤에 자동으로 공백을 삽입할지 여부 입니다.
"files.associations" ⤍ "*.json": "jsonc" : .json 파일을 jsonc(주석이 있는 JSON) 형식으로 인식하도록 설정합니다.
"eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"] : ESLint가 TypeScript, React, JavaScript 파일을 검사하도록 설정합니다.
"eslint.workingDirectories" : [{"mode":"auto"}] : ESLint 작업 디렉토리를 자동으로 감지하도록 설정합니다.
"editor.defaultFormatter": "esbenp.prettier-vscode" : VSCode의 기본 코드 포맷터로 Prettier를 사용합니다.
"eslint.useFlatConfig" : ESLint의 설정방식이 v8.21.0 부터 Flat Config를 지원하면서, 구성 형식을 Flat Config으로 할지 여부 설정.
"css.lint.unknownAtRules": "ignore" : VSCode에서 CSS의 "Unknown At Rules" 경고를 무시하도록 설정.
"scss.lint.unknownAtRules": "ignore" : VSCode에서 scss의 "Unknown At Rules" 경고를 무시하도록 설정.
"less.lint.unknownAtRules": "ignore" : VSCode에서 less의 "Unknown At Rules" 경고를 무시하도록 설정.
"[markdown]": : Markdown 파일을 편집할 때 자동으로 코드 서식을 정리하지 않도록 설정.
"[mdx]": : MDX 파일을 편집할 때 자동으로 코드 서식을 정리하지 않도록 설정.

오프라인일경우 설정 추가함

"update.mode": "none",
"telemetry.telemetryLevel": "off",
"extensions.autoUpdate": false,
"extensions.autoCheckUpdates": false

Frontend 개발 코드 내려받기

Git 레포지토리 url

https://github.com/orgs/nic-company-mf-react/repositories
개발 코드를 내려받기 위해서는 계정 및 권한이 필요합니다. (해당 권한은 담당자에게 요청)

작업 폴더 생성 및 Frontend 소스 코드 받기

먼저 PC에 작업 할 폴더를 생성합니다.

# C:\my\ 디렉토리에서 폴더를 생성한다고 가정.
# 내가 작업 할 폴더를 'frontend-mf' 라고 하고 해당 폴더를 생성.
mkdir frontend-mf
# C:\my\frontend-mf 폴더가 생성 됨.

생성한 frontend-mf 폴더로 이동하여 git clone을 실행하여 multirepo-mfe-boilerplate 코드를 내려 받습니다.

# host 애플리케이션 레포지토리에서 코드를 내려받습니다.
git clone https://github.com/nic-company-mf-react/mfe-app-main.git

# remote 애플리케이션 레포지토리에서 코드를 내려받습니다.
git clone https://github.com/nic-company-mf-react/mfe-app-remote1.git

# 공유 라이브러리리 레포지토리에서 코드를 내려받습니다.
git clone https://github.com/nic-company-mf-react/mfe-lib-shared.git

git clone하여 내려받은 소스를 확인해보면 아직 node_modules폴더가 없는상태입니다. 의존성 라이브러리를 설치면 node_modules폴더를 자동생성합니다.
```
# 프로젝트 루트 폴더에서 의존성 라이브러리 설치
npm install
```

VSCode에서 로컬 서버 띄우고 브라우저로 확인해 보기

⭐ 최초 내려받은 Frontend 소스에 node_modules가 없으면 Frontend 로컬 서버를 띄울 수 없습니다. 반드시 의존성 라이브러리를 설치하여 node_modules를 추가 해야 합니다.
- 인터넷이 되는 환경에서는 npm install 명령어로 바로 설치 가능.
의존성 라이브러리(node_modules) 설치가 모두 완료 되면, 로컬 PC에서 로컬 서버를 띄우고 브라우저로 확인할 수 있습니다.
로컬 서버 띄우기
- Host 앱, Remote 앱은 다음과 같이 명령어로 띄울 수 있습니다.
```
npm run dev
```
Chrome 브라우저를 띄우고 http://localhost:5000 확인하면 다음과 같이 확인할 수 있습니다.(url port와 화면 결과물은 다를 수 있음.)

Node.js 설치​

Git 설치​

pnpm workspaces 설치 (필요시에만)​

pnpm Workspaces와 함께 모노레포에 도움이 되는 도구들​

1. pnpm 온라인 설치​

2. pnpm 오프라인 설치​

Visual Studio Code 설치​

VSCode Extensions 온라인 설치 방법​

VSCode Extensions 오프라인 VSIX설치 방법(외부 인터넷이 되지 않는 환경일때 )​

Cursor 설치 (선택)​

Chrome Browser 설치​

React Developer Tools 설치 (크롬 브라우저 확장 프로그램)​

Redux DevTools 설치 (크롬 브라우저 확장 프로그램)(필요시에만)​

TanStack Query(React Query) DevTools 설치 (크롬 브라우저 확장 프로그램)(필요시에만)​

VSCode에서 Git bash 쉘(Shll)프로그램을 사용하자.​

Visual Studio Code (VSCode) 코드편집기 설정​

settings.json 셋팅 (VSCode 설정)​

settings.json 설정​

Frontend 개발 코드 내려받기​

작업 폴더 생성 및 Frontend 소스 코드 받기​

VSCode에서 로컬 서버 띄우고 브라우저로 확인해 보기​