Blast React Template

@blastlabs/react-web 템플릿은 (주)블라스트에서 사용하는 React 기반의 웹 개발 템플릿입니다.
이 템플릿은 pnpm을 통해 패키지를 관리하며, FSD (Folder Structure by Feature) 아키텍처를 따르고 있습니다.

또한, npx CLI 명령어를 통해 손쉽게 템플릿을 다운로드 받아 새로운 프로젝트를 빠르게 시작할 수 있습니다.

목차

• 📦 설치 및 실행
• 📂 폴더 구조
• 📌 폴더 설명
• 🚀 사용 기술 스택
• 📜 프로젝트 스크립트
• 📌 코드 스타일

📦 설치 및 실행

1️⃣ 템플릿 내려받기

# 프로젝트 생성
npx @blastlabs/blaster-cli

# react-web 선택
$ react-web

# 새 프로젝트 명 입력
$ <project-name>

2️⃣ 프로젝트 실행

pnpm install  # 패키지 설치
pnpm dev      # 개발 서버 실행

📂 폴더 구조

이 템플릿은 FSD(Folder Structure by Feature) 아키텍처를 기반으로 구성되어 있습니다.

├── src
│ ├── app            // React Router 기반 페이지 구성 및 라우팅 설정
│ │ ├── auth
│ │ │ ├── _routes.tsx
│ │ │ ├── signin.tsx
│ │ │ └── login.tsx
│ │ └── Router.tsx
│ ├── views          // UI 레이아웃 및 컨테이너 정의
│ │ ├── home
│ │ │   └── HomePage.tsx
│ │ └── auth
│ │     ├── LoginPage.tsx
│ │     └── SignPage.tsx
│ ├── entities       // 데이터 모델 정의 (Zod 사용)
│ ├── features       // 복합적인 비즈니스 로직
│ └── shared         // 공용 모듈 및 유틸리티 관리
│   ├── api
│ │ ├── hooks
│   ├── i18n
│   ├── lib
│   ├── store
│   ├── ui
│   └── utils

📌 폴더 설명

app/

• React의 BrowserRouter를 기반으로 페이지 구성 및 라우팅을 담당합니다.

views/

• 각 페이지별 UI 컴포넌트와 컨테이너를 정의하여, 화면 구성 요소를 분리해 관리합니다.

entities/

• 프론트엔드에서 사용하는 데이터 모델을 정의합니다.
• Zod 등을 활용하여 타입 안전성을 보장합니다.
  • 예: 서버의 snake_case 데이터를 프론트엔드에서 camelCase 형태로 변환.
  • 예: created_at, updated_at 등의 string 타입 데이터를 Date 타입으로 변환.

features/

• 여러 페이지에서 복합적으로 사용되는 비즈니스 로직을 처리하는 기능을 포함합니다.

shared/

• 프로젝트 전반에서 재사용되는 공용 모듈을 관리하는 폴더입니다.
• 주요 하위 폴더:
  • api/ → 공용 API 요청 관리
  • hooks/ 공용 커스텀 hook 관리
  • i18n/ → 다국어 스크립트 관리
  • lib/ → 외부 라이브러리 및 헬퍼 함수
  • store/ → 전역 상태 관리
  • ui/ → 공통 UI 컴포넌트 및 디자인 시스템
  • utils/ → 유틸리티 함수 모음

🚀 사용 기술 스택

| 기술 | 설명 | | --------------------------------------- | ----------------------------- | | vite (^6.x) | 빠른 개발 서버 및 번들링 도구 | | React ^18 | 최신 React 기능 활용 | | TypeScript | 타입 안전성 보장 | | Tailwind CSS | 스타일링 시스템 적용 | | Zod | 데이터 모델 검증 | | ESLint & Prettier | 코드 스타일 유지 및 정리 | | React Query (@tanstack/react-query) | 데이터 페칭 및 상태 관리 |

📜 프로젝트 스크립트

| 명령어 | 설명 | | -------------- | ---------------------------------------- | | pnpm dev | 개발 서버 실행 (localhost:3000) | | pnpm build | TypeScript 컴파일 후 Vite 번들 빌드 수행 | | pnpm preview | 빌드된 프로젝트 실행 | | pnpm lint | ESLint 코드 검사 |

📌 코드 스타일

이 프로젝트는 사내 Lint 및 Prettier 패키지인
@blastlabs/eslint-plugin-react & @blastlabs/prettier-config
를 적용하여 코드 스타일을 유지합니다.