Blast Next.js Template

@blastlabs/nextjs-web는 (주)블라스트에서 사용하는 Next.js 기반의 웹 개발 템플릿입니다.
이 프로젝트는 pnpm을 사용하여 패키지를 관리하며, FSD(Folder Structure by Feature) 아키텍처를 따릅니다.

또한, npx CLI 명령어를 통해 템플릿을 간편하게 다운로드하여 빠르게 프로젝트를 시작할 수 있습니다.

목차

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

📦 설치 및 실행

1️⃣ 템플릿 내려받기

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

# nextjs-web 선택
$ nextjs-web

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

2️⃣ 프로젝트 실행

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

📂 폴더 구조

이 프로젝트는 FSD(Folder Structure by Feature) 아키텍처를 기반으로 구성되어 있습니다.

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

📌 폴더 설명

app/

• Next.js의 App Router를 기반으로 페이지를 구성합니다.
• 모든 페이지 및 레이아웃 관련 파일이 포함됩니다.

views/

• UI 컴포넌트 및 컨테이너를 정의하는 폴더입니다.
• app 폴더와 동일한 구조를 가지며, 페이지별 UI를 분리하여 관리합니다.

entities/

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

features/

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

shared/

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

🚀 사용 기술 스택

| 기술 | 설명 | | --------------------- | ------------------------ | | Next.js 15 | 최신 버전의 Next.js 지원 | | React 19 | 최신 React 버전 활용 | | TypeScript | 타입 안전성 보장 | | Tailwind CSS | 스타일링 시스템 적용 | | Zod | 데이터 모델 검증 | | ESLint & Prettier | 코드 스타일 유지 및 정리 |

📜 프로젝트 스크립트

| 명령어 | 설명 | | ------------ | --------------------------------- | | pnpm dev | 개발 서버 실행 (localhost:3000) | | pnpm build | 프로젝트 빌드 | | pnpm start | 빌드된 프로젝트 실행 | | pnpm lint | ESLint 코드 검사 |

📌 코드 스타일

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