uwksa.ca 수정 가이드¶

uwksa.ca 프론트엔드 코드를 수정하고 반영하는 방법을 안내합니다.

사전 준비¶

다음 도구가 설치되어 있어야 합니다:

Git - 버전 관리
Node.js (v18 이상) - JavaScript 런타임
npm - 패키지 매니저 (Node.js와 함께 설치됨)
코드 에디터 - VS Code 권장

1단계: 저장소 클론 (최초 1회)¶

처음 작업하는 경우, 저장소를 클론합니다.

git clone https://github.com/therealuwksatech/uwksa.ca.git
cd uwksa.ca

SSH를 사용하는 경우

GitHub SSH를 사용하려면 서버 접속 가이드의 SSH 키 설정을 먼저 완료한 후 다음 명령어를 사용하세요:

git clone [email protected]:therealuwksatech/uwksa.ca.git

이미 클론한 경우 이 단계를 건너뛰세요.

2단계: 최신 코드 가져오기¶

작업을 시작하기 전에 반드시 최신 코드를 가져옵니다.

git pull origin main

주의

항상 작업 시작 전에 git pull을 실행하세요. 다른 팀원의 변경 사항과 충돌을 방지할 수 있습니다.

3단계: 의존성 설치¶

새로운 패키지가 추가되었을 수 있으므로 의존성을 설치합니다.

npm install

4단계: 개발 서버 실행¶

로컬에서 변경 사항을 실시간으로 확인하면서 작업합니다.

npm run dev

브라우저가 자동으로 열리며 http://localhost:3000에서 사이트를 확인할 수 있습니다. 코드를 수정하면 자동으로 브라우저에 반영됩니다 (Hot Module Replacement).

5단계: 코드 수정¶

수정할 대상에 따라 해당 파일을 찾아 수정합니다:

수정 대상	파일 위치	상세 가이드
팀원 정보	`src/data/teamData.ts`	자주 하는 작업
이벤트	`src/pages/HomePage.tsx`, `EventsPage.tsx`	자주 하는 작업
제휴 식당	`src/pages/MembershipPage.tsx`	자주 하는 작업
소셜 링크	`src/data/socialLinks.ts`	자주 하는 작업
새 페이지	`src/App.tsx` + 새 파일	자주 하는 작업

다국어 콘텐츠¶

한국어/영어 텍스트는 LocalizedContent<T> 타입으로 관리됩니다. 텍스트를 수정할 때 한국어와 영어 모두 업데이트해야 합니다:

import { LocalizedContent } from '@/types';

const content: LocalizedContent<{ title: string }> = {
  ko: { title: '한국어 제목' },
  en: { title: 'English Title' },
};

@/ import 경로

@/는 ./src 폴더를 가리키는 path alias입니다. 예를 들어 @/components/ui/button은 src/components/ui/button과 같습니다. 자세한 내용은 프로젝트 개요를 참고하세요.

6단계: 변경 사항 확인¶

개발 서버에서 수정한 내용이 정상적으로 보이는지 확인합니다:

다크 모드와 라이트 모드 모두에서 확인
한국어와 영어 모두에서 확인
모바일 화면 크기에서도 확인 (브라우저 개발자 도구 사용)

7단계: 변경 사항 커밋¶

수정이 완료되면 Git에 변경 사항을 저장합니다.

# 변경된 파일 확인
git status

# 변경 사항 스테이징
git add <수정한 파일>
# 예: git add src/pages/HomePage.tsx

# 커밋 메시지 작성
git commit -m "변경 내용을 간결하게 설명"
# 예: git commit -m "홈페이지 히어로 섹션 텍스트 업데이트"

커밋 메시지 팁

무엇을 왜 변경했는지 간결하게 작성합니다
한 커밋에는 하나의 논리적 변경만 포함합니다
예시: "이벤트 페이지에 2025 봄 행사 추가", "푸터 소셜 링크 업데이트"

8단계: 원격 저장소에 푸시¶

커밋한 변경 사항을 원격 저장소에 올립니다.

git push origin main

충돌 발생 시

git push가 실패하면 다른 팀원이 먼저 변경 사항을 올린 것일 수 있습니다. 이 경우:

git pull origin main

충돌이 발생하면 해당 파일을 열어 수동으로 해결한 후 다시 커밋하고 푸시합니다.

배포¶

main 브랜치에 푸시하면 Cloudflare Pages를 통해 자동으로 배포됩니다. 별도의 배포 작업은 필요하지 않습니다.

전체 워크플로우 요약¶

git pull origin main          # 최신 코드 가져오기
npm install                   # 의존성 설치
npm run dev                   # 개발 서버 실행
# ... 코드 수정 ...
git add <수정한 파일>           # 변경 사항 스테이징
git commit -m "변경 설명"       # 커밋
git push origin main          # 원격 저장소에 푸시

빌드¶

프로덕션 빌드가 필요한 경우:

npm run build

빌드 결과물은 build/ 폴더에 생성됩니다.

자주 발생하는 문제¶

`npm install` 실패¶

Node.js 버전이 18 이상인지 확인합니다:

node --version

v18 미만이라면 Node.js 공식 사이트에서 LTS 버전을 설치하세요.

개발 서버가 실행되지 않음¶

포트 3000이 이미 사용 중일 수 있습니다. 다음 명령어로 확인합니다:

# Mac/Linux
lsof -i :3000

# Windows
netstat -ano | findstr :3000

기존 프로세스를 종료한 후 다시 시도하세요.

`git push` 거부됨¶

먼저 git pull origin main으로 최신 변경 사항을 가져온 후 다시 시도합니다.

TypeScript 타입 오류¶

@/ import 경로에서 타입 오류가 발생하면 VS Code에서 TypeScript Server를 재시작합니다:

Cmd+Shift+P (Mac) 또는 Ctrl+Shift+P (Windows/Linux)
TypeScript: Restart TS Server 선택

`Module not found` 오류¶

의존성을 새로 설치합니다:

rm -rf node_modules
npm install

이미지가 표시되지 않음¶

파일명의 대소문자가 코드에서 import한 경로와 정확히 일치하는지 확인합니다
이미지 파일명은 <팀>_<영문이름>.<확장자> 패턴을 따릅니다 (예: tech_donghun.jpeg)
자세한 네이밍 규칙은 자주 하는 작업 - 프로필 사진 등록을 참고하세요

추가 팁¶

VS Code 추천 확장¶

Tailwind CSS IntelliSense - Tailwind 클래스 자동 완성 및 미리보기
ES7+ React/Redux/React-Native snippets - React 컴포넌트 코드 스니펫

반응형 디자인 확인¶

브라우저 개발자 도구의 반응형 모드를 사용하면 모바일 화면을 쉽게 확인할 수 있습니다:

Mac: Cmd+Shift+M (개발자 도구가 열린 상태에서)
Windows/Linux: Ctrl+Shift+M

커밋 전 변경사항 확인¶

# 아직 스테이징하지 않은 변경사항 확인
git diff

# 스테이징한 변경사항 확인 (커밋될 내용)
git diff --staged