🎯 신입 개발자 온보딩 가이드

환영합니다! 이 문서는 GMD Soft Platform Frontend 프로젝트에 처음 합류한 개발자가 첫 주 동안 따라갈 수 있는 단계별 가이드입니다.

📋 목차

• 개발 환경 설정
• 프로젝트 이해하기
• 작업 시작
• 자주 하는 작업 패턴
• 트러블슈팅
• 도움 받기

---

개발 환경 설정

1. 필수 도구 설치

Node.js 및 Yarn

# Node.js 버전 확인 (18 이상 권장)
node -v

# Yarn 설치
npm install -g yarn

# Yarn 버전 확인
yarn -v

Git 설정

# Git 사용자 정보 설정
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

VS Code 설치

• VS Code 다운로드

필수 VS Code 확장 프로그램:

• ESLint - 코드 품질 검사
• Prettier - 코드 포맷팅
• Vanilla Extract - CSS-in-JS 문법 강조
• SonarQube for IDE - 코드 분석

2. 프로젝트 클론 및 설정

# 프로젝트 클론
git clone https://github.com/gmdsoft/md.platform.frontend
cd frontend

# 의존성 설치
yarn install

# 환경 변수 설정
cp .env.example .env
# .env 파일을 열어서 필요한 값 설정 (팀 내 프론트엔드 개발자에게 문의)

# 로컬 개발 서버 실행
npm run local

브라우저에서 http://localhost:5173 접속하여 앱이 정상적으로 실행되는지 확인하세요.

3. Storybook 실행

# Storybook 실행
npm run storybook

브라우저에서 http://localhost:6006 접속하여 디자인 시스템을 확인하세요.

4. VS Code 설정

.vscode/settings.json 파일이 프로젝트에 포함되어 있어 자동으로 적용됩니다.

권장 설정:

• Format On Save: 활성화
• Auto Save: onFocusChange
• Tab Size: 2

프로젝트 이해하기

1. 문서 읽기

https://d1u1qy5bpe3a3.cloudfront.net/

• 프론트엔드 개발 문서
  • TypeScript 컨벤션
  • React 컨벤션
  • 파일 네이밍 규칙
  • 에러 처리
  • 상태 관리

2. Storybook으로 디자인 시스템 학습

Storybook을 열어서 다음 컴포넌트들을 살펴보세요:

Atoms (기본 컴포넌트):

• Button: 다양한 variant (primary, secondary, danger 등)
• Input: 입력 필드
• Card: 카드 컨테이너
• Typography: 텍스트 스타일

Molecules (조합 컴포넌트):

• Modal: 모달 다이얼로그
• Table: 테이블 (가상화 지원)
• Select: 드롭다운 선택

Organisms (복잡한 컴포넌트):

• VideoPlayer: 비디오 플레이어
• Toast: 알림 메시지

3. 주요 기술 스택 학습

프로젝트에서 사용하는 핵심 라이브러리를 학습하세요:

필수 학습:

• React 18 - 기본 React 훅 (useState, useEffect, useMemo, useCallback)
• TypeScript - 타입 시스템
• TanStack Query - 서버 상태 관리 (useQuery, useMutation)
• Vanilla Extract - CSS-in-JS
• React Router - 라우팅

선택 학습:

• Vitest - 테스트 프레임워크
• Storybook - 컴포넌트 문서화
• Feature-Sliced Design - 아키텍처 패턴

5. 코드 탐색

다음 파일들을 직접 열어서 코드를 읽어보세요:

1. 간단한 컴포넌트:

• src/shared/ui/atoms/Button/Button.tsx - 기본 버튼 컴포넌트
• src/shared/ui/atoms/Button/Button.css.ts - Vanilla Extract 스타일

2. 커스텀 훅:

• src/shared/hooks/useToast.ts - Toast 알림 훅
• src/features/user/model/useForm.ts - 폼 관리 훅

3. API 호출:

• src/entities/user/api/user.api.ts - User API 함수
• src/entities/user/api/user.dto.ts - DTO 타입
• src/shared/api/base.ts - Axios 인터셉터

4. 페이지:

• src/pages/SignIn/SignIn.tsx - 로그인 페이지
• src/pages/Home/Home.tsx - 홈 페이지

작업 시작

1. 간단한 이슈 선택

처음에는 다음과 같은 간단한 작업으로 시작하세요:

• UI 컴포넌트에 새로운 variant 추가
• 기존 컴포넌트에 props 추가
• 간단한 버그 수정
• 문서 수정

추천 첫 이슈:

• Button 컴포넌트에 새로운 size variant 추가
• Input 컴포넌트에 icon props 추가
• 작은 스타일 개선

2. 브랜치 생성

# 최신 main 브랜치로 체크아웃
git checkout main
git pull origin main

# 새 브랜치 생성
git checkout -b feature/add-button-size-variant

# 브랜치 네이밍 규칙:
# - feature/* : 새로운 기능
# - fix/*     : 버그 수정
# - refactor/*: 리팩토링
# - test/*    : 테스트 추가/수정
# - chore/*   : 기타 작업
# - docs/*    : 문서 수정
# - style/*   : 스타일/포맷팅
# - build/*   : 빌드 관련 작업

3. 코드 작성

예시: Button 컴포넌트에 size variant 추가

Step 1: 타입 정의

// src/shared/ui/atoms/Button/Button.tsx
type ButtonSize = 'small' | 'medium' | 'large';

type ButtonProps = Readonly<{
  size?: ButtonSize;
  // ... 기존 props
}>;

Step 2: 스타일 추가

// src/shared/ui/atoms/Button/Button.css.ts
export const small = style({
  padding: `${token.layout.spacing.size80} ${token.layout.spacing.size120}`,
  fontSize: '14px',
});

export const medium = style({
  padding: `${token.layout.spacing.size120} ${token.layout.spacing.size160}`,
  fontSize: '16px',
});

export const large = style({
  padding: `${token.layout.spacing.size160} ${token.layout.spacing.size200}`,
  fontSize: '18px',
});

Step 3: 컴포넌트에 적용

export default function Button({ size = 'medium', ...props }: ButtonProps) {
  const sizeClass = size === 'small' ? styles.small : size === 'large' ? styles.large : styles.medium;

  return (
    <button className={`${styles.base} ${sizeClass}`}>
      {props.children}
    </button>
  );
}

Step 4: Storybook 스토리 추가

// src/shared/ui/atoms/Button/Button.stories.tsx
export const AllSizes: Story = {
  render: () => (
    <Flex gap={8}>
      <Button size="small">Small</Button>
      <Button size="medium">Medium</Button>
      <Button size="large">Large</Button>
    </Flex>
  ),
};

4. 테스트 실행

# 린트 검사
npm run lint

# 타입 체크
npm run build

# 테스트 (필요시)
npm run test

# Storybook 확인
npm run storybook

5. 커밋 및 푸시

# 변경사항 확인
git status

# 파일 추가
git add src/shared/ui/atoms/Button/

# 커밋 (Husky가 자동으로 lint 및 format 실행)
git commit -m "feat: Button 컴포넌트에 size variant 추가"

# 푸시
git push origin feature/add-button-size-variant

6. Pull Request 생성

GitHub에서 Pull Request를 생성하세요.

7. 코드 리뷰 및 머지

• 리뷰어의 피드백을 받고 수정
• Approve를 받으면 머지

자주 하는 작업 패턴

1. 새로운 페이지 추가

# 1. 페이지 컴포넌트 생성
src/pages/UserProfile/UserProfile.tsx
src/pages/UserProfile/UserProfile.css.ts

# 2. 라우트 추가
src/shared/config/routes.ts
src/app/routers/index.tsx

# 3. 메뉴 추가 (필요시)

예시 코드:

// src/pages/UserProfile/UserProfile.tsx
export default function UserProfile() {
  const { data: user } = useQuery({
    queryKey: queryKeys.user.current(),
    queryFn: getCurrentUser,
  });

  return (
    <div>
      <h1>{user?.name}</h1>
    </div>
  );
}

// src/shared/config/routes.ts
export const ROUTES = {
  USER_PROFILE: '/user/profile',
  // ...
};

// src/app/routers/index.tsx
<Route path={ROUTES.USER_PROFILE} element={<UserProfile />} />

2. API 연동하기

Step 1: DTO 정의

// entities/user/api/user.dto.ts
export type UserDto = {
  id: string;
  name: string;
  email: string;
};

Step 2: API 함수 작성

// entities/user/api/user.api.ts
export async function getUser(userId: string): Promise<UserDto> {
  const { data } = await api.get<UserDto>(`/api/users/${userId}`);
  return data;
}

Step 3: Query Key 추가

// shared/config/queryKeys.ts
export const queryKeys = {
  user: {
    all: ['user'] as const,
    detail: (id: string) => [...queryKeys.user.all, 'detail', id] as const,
  },
};

Step 4: useQuery 사용

// features/user/model/useUser.ts
export function useUser(userId: string) {
  return useQuery({
    queryKey: queryKeys.user.detail(userId),
    queryFn: () => getUser(userId),
  });
}

Step 5: 컴포넌트에서 사용

function UserProfile({ userId }: { userId: string }) {
  const { data, isLoading, error } = useUser(userId);

  if (isLoading) return <div>로딩 중...</div>;
  if (error) return <div>에러 발생</div>;

  return <div>{data.name}</div>;
}

3. 폼 구현하기

import { useForm } from '@shared/hooks';

function SignUpForm() {
  const { formState, formErrors, handleInputChange, isFormValid } = useForm({
    initialValues: {
      email: '',
      password: '',
    },
    validation: {
      email: (value) => {
        if (!value.includes('@')) return '올바른 이메일을 입력하세요';
        return null;
      },
      password: (value) => {
        if (value.length < 8) return '비밀번호는 8자 이상이어야 합니다';
        return null;
      },
    },
  });

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    if (!isFormValid) return;
    // API 호출
  };

  return (
    <form onSubmit={handleSubmit}>
      <Input
        value={formState.email}
        error={formErrors.email}
        onChange={(e) => handleInputChange('email', e.target.value)}
      />
      <Input
        type="password"
        value={formState.password}
        error={formErrors.password}
        onChange={(e) => handleInputChange('password', e.target.value)}
      />
      <Button type="submit">제출</Button>
    </form>
  );
}

4. 에러 처리하기

import { useMutation } from '@tanstack/react-query';
import { isApiError } from '@shared/api/error-handler';
import { useToast } from '@shared/hooks';

function Component() {
  const toast = useToast();

  const mutation = useMutation({
    mutationFn: updateUser,
    onSuccess: () => {
      toast.success('성공적으로 저장되었습니다.');
    },
    onError: (error) => {
      if (isApiError(error)) {
        toast.error(error.message);
      } else {
        toast.error('알 수 없는 오류가 발생했습니다.');
      }
    },
  });

  return <button onClick={() => mutation.mutate(data)}>저장</button>;
}

5. 새 에러 코드 추가

// entities/user/api/user.error.ts
export enum UserErrorCode {
  USER_NOT_FOUND = 'USER-1000',
  DUPLICATED_EMAIL = 'USER-1001',
  // 새로운 에러 코드 추가
  INVALID_PHONE_NUMBER = 'USER-1007',
}

export const userErrorMessages: Record<UserErrorCode, () => string> = {
  // ...
  [UserErrorCode.INVALID_PHONE_NUMBER]: () => '올바른 전화번호를 입력하세요.',
};

// shared/api/error.ts
import { UserErrorCode } from '@entities/user/api/user.error';

export type ErrorCode =
  | CommonErrorCode
  | UserErrorCode
  // 다른 도메인 에러 추가
  | VerificationErrorCode;

6. 공통 컴포넌트 만들기

// shared/ui/atoms/Badge/Badge.tsx
import * as styles from './Badge.css';

type BadgeProps = Readonly<{
  children: React.ReactNode;
  color?: 'primary' | 'secondary' | 'danger';
}>;

export default function Badge({ children, color = 'primary' }: BadgeProps) {
  return <span className={`${styles.base} ${styles[color]}`}>{children}</span>;
}

// shared/ui/atoms/Badge/Badge.css.ts
import { style } from '@vanilla-extract/css';
import { token } from '@shared/styles';

export const base = style({
  padding: `${token.layout.spacing.size40} ${token.layout.spacing.size80}`,
  borderRadius: `${token.layout.radius.sm}`,
  fontSize: '12px',
  fontWeight: 'bold',
});

export const primary = style({
  backgroundColor: `${token.foundation.primary.base}`,
  color: `${token.text.onPrimary}`,
});

// shared/ui/atoms/Badge/Badge.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import Badge from './Badge';

const meta = {
  title: 'Atoms/Badge',
  component: Badge,
  tags: ['autodocs'],
} satisfies Meta<typeof Badge>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: {
    children: 'Primary',
    color: 'primary',
  },
};

---

트러블슈팅

자주 발생하는 에러

1. Cannot find module 에러

# 의존성 재설치
rm -rf node_modules
yarn install

2. 린트 에러

# 자동 수정
npm run lint:fix

3. 타입 에러

// ❌ 잘못된 예
const user = data; // data의 타입이 명확하지 않음

// ✅ 올바른 예
const user: User = data;

4. Storybook이 실행되지 않음

# Storybook 캐시 삭제
rm -rf node_modules/.cache/storybook
npm run storybook

5. Git pre-commit hook 실패

# 변경사항 확인
git status

# 린트 수동 실행
npm run lint:fix

# 다시 커밋
git commit -m "..."

6. API 연동 에러

• 네트워크 탭에서 요청/응답 확인
• .env.local 파일의 VITE_BASE_URL 확인
• 백엔드 서버가 실행 중인지 확인

화이팅! 🚀