스크래치 모노레포 (Scratch Monorepo)

스크래치 프로젝트를 위한 모노레포 관리 시스템

📋 목차

• 프로젝트 소개
• 시스템 요구사항
• 설치 방법
• 빌드 방법
• 실행 방법
• 프로젝트별 명령어
• CI/CD 설정
• 문제 해결
• Nx 명령어 활용
• 개발 팁
• 기여 방법

🚀 프로젝트 소개

이 저장소는 Nx 도구를 활용하여 여러 스크래치 관련 프로젝트를 하나의 모노레포로 관리합니다. 포함된 주요 프로젝트:

프로젝트	설명
scratch-gui	스크래치 편집기의 사용자 인터페이스
scratch-vm	스크래치 프로젝트를 실행하는 가상 머신
scratch-blocks	블록 기반 프로그래밍 인터페이스
scratch-l10n	다국어 지원 라이브러리

💻 시스템 요구사항

• Node.js v16 이상 (v18 권장)
• npm v8 이상
• Git

📥 설치 방법

1. 저장소 클론:

git clone https://github.com/your-repo/scratch-monorepo.git
cd scratch-monorepo

2. 의존성 설치:

npm install

3. 누락된 Babel 관련 의존성 설치 (ESLint 오류 수정):

npm install --save-dev @babel/eslint-parser

🛠 빌드 방법

전체 프로젝트 빌드

npx nx run-many --target=build --all

특정 프로젝트 빌드

# scratch-gui 프로젝트 빌드
npx nx run scratch-gui:build

# 캐시 문제가 있는 경우 캐시 사용 안 함
npx nx run scratch-gui:build --skip-nx-cache

▶️ 실행 방법

직접 실행

cd scratch-gui
npm start

Nx를 통한 실행

npx nx run scratch-gui:serve

참고: 기본적으로 애플리케이션은 http://localhost:8601/ 주소에서 실행됩니다.

🧩 프로젝트별 명령어

scratch-vm

# 빌드
cd scratch-vm
npm run build

# 테스트
cd scratch-vm
npm test

scratch-blocks

# 빌드 (prepublish 스크립트 사용)
cd scratch-blocks
npm run prepublish

# 테스트
cd scratch-blocks
npm test

scratch-gui

# 빌드
cd scratch-gui
npm run build

# 개발 서버 실행
cd scratch-gui
npm start

# 테스트
cd scratch-gui
npm test

🔄 CI/CD 설정

이 프로젝트는 GitHub Actions를 사용하여 CI/CD를 구성하고 있습니다. 다음과 같은 워크플로우가 설정되어 있습니다:

CI 워크플로우

.github/workflows/ci.yml

• 트리거: main 및 develop 브랜치 푸시, 풀 리퀘스트
• 작업:
  • 테스트 실행
  • 영향받은 프로젝트 빌드
  • NX 캐시 사용 최적화

에이전트 워크플로우

.github/workflows/agents.yml

• 트리거: main 및 develop 브랜치 푸시, 풀 리퀘스트
• 작업:
  • 병렬 빌드를 위한 NX Cloud 에이전트 실행

배포 워크플로우

.github/workflows/deploy.yml

• 트리거: main 브랜치 푸시, 수동 실행
• 작업:
  • scratch-gui 프로젝트 빌드
  • GitHub Pages에 배포

CI/CD 환경 변수 설정

GitHub 저장소의 Settings > Secrets and variables > Actions에서 다음 시크릿 값을 설정해야 합니다:

• NX_CLOUD_ACCESS_TOKEN: NX Cloud 액세스 토큰 (선택사항)
• SLACK_WEBHOOK_URL: Slack 알림을 위한 Webhook URL (선택사항)
• CNAME: 사용자 정의 도메인 이름 (선택사항)

⚠️ 문제 해결

캐시 관련 문제

Nx 캐시 문제가 발생하면 다음 명령어로 캐시를 초기화합니다:

rm -rf .nx/cache
npx nx reset

일반적인 빌드 오류

문제	해결 방법
React 버전 충돌	프로젝트는 React 18.2.0과 호환됩니다. React 19 사용 시 충돌이 발생할 수 있습니다.
scratch-blocks 빌드 오류	scratch-blocks에는 build 스크립트 대신 prepublish 스크립트를 사용해야 합니다.
ESLint 오류	누락된 @babel/eslint-parser 설치로 해결 가능합니다.

애플리케이션 실행 문제

애플리케이션이 브라우저에 표시되지 않는 경우:

1. 올바른 URL에 접속하는지 확인 (기본 http://localhost:8601/)
2. 브라우저 개발자 콘솔(F12)에서 오류 메시지 확인
3. 다른 브라우저로 시도
4. 브라우저 캐시 삭제 후 재시도
5. 포트 충돌이 있는 경우 다른 포트 사용

🔄 Nx 명령어 활용

의존성 그래프 확인

npx nx graph

특정 프로젝트 실행

npx nx run [프로젝트명]:[타겟]

예: npx nx run scratch-gui:build

여러 프로젝트 동시 실행

npx nx run-many --target=[타겟] --projects=[프로젝트1],[프로젝트2]

변경된 프로젝트만 실행

npx nx affected --target=[타겟]

💡 개발 팁

1. 각 프로젝트는 독립적인 package.json 파일을 가지고 있으므로, 특정 프로젝트에만 의존성을 추가하려면 해당 디렉토리에서 npm install 명령을 실행하세요

2. 공통 의존성은 루트 package.json에 추가하는 것이 좋습니다.

3. 프로젝트 구조를 변경할 때는 project.json 파일과 nx.json 파일을 함께 업데이트해야 합니다.

4. 개발 중에는 각 프로젝트의 변경 사항이 다른 프로젝트에 미치는 영향을 고려하세요.

🤝 기여 방법

1. 기능 개발이나 버그 수정은 별도의 브랜치에서 작업하세요.
2. 코드 변경 전후로 테스트를 실행하여 기능이 제대로 작동하는지 확인하세요.
3. 풀 리퀘스트를 제출하기 전에 코드 형식과 린트 규칙을 준수했는지 확인하세요.

---

이 프로젝트는 MIT 라이선스 하에 배포됩니다.