ExecuteJS
가이드
개발하기
가이드
개발하기

개발 가이드

ExecuteJS 프로젝트의 개발 환경 설정과 기여 방법을 안내합니다.

개발 환경 설정

1. 필수 도구 설치

mise를 사용한 자동 설치 (권장)

프로젝트는 mise.toml을 통해 런타임 버전을 자동으로 관리합니다:

# mise 설치 (아직 설치하지 않은 경우)
curl https://mise.run | sh

# 프로젝트 디렉토리에서 실행
mise install

# 또는 자동으로 활성화되도록 설정
mise activate

이제 프로젝트 디렉토리에서 자동으로 올바른 버전의 Node.js, pnpm, Rust가 사용됩니다.

수동 설치

# Node.js 22 LTS 설치 (nvm 사용 권장)
nvm install 22
nvm use 22

# pnpm 설치
npm install -g pnpm

# Rust 설치
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Tauri CLI 설치
cargo install tauri-cli

2. 프로젝트 설정

# 의존성 설치
pnpm install

# 개발 서버 실행
pnpm tauri:dev

개발 워크플로우

코드 품질 관리

# 린트 검사
pnpm lint

# 린트 자동 수정
pnpm lint:fix

# 포맷팅
pnpm format

# 포맷팅 검사
pnpm format:check

# 타입 검사
pnpm type-check

테스트

# 프론트엔드 테스트
pnpm test

# Rust 테스트
cargo test

# 모든 테스트
pnpm test --run
cargo test --all-targets

빌드

# 개발 빌드
pnpm tauri:dev

# 프로덕션 빌드
pnpm tauri:build

CI/CD

프로젝트는 GitHub Actions를 통해 자동화된 품질 관리를 제공합니다:

  • JavaScript/TypeScript Lint: oxlint를 통한 코드 품질 검사
  • Rust Lint: rustfmt와 clippy를 통한 Rust 코드 검사
  • Frontend Test: vitest를 통한 프론트엔드 테스트
  • Rust Test: cargo test를 통한 Rust 테스트
  • Build Check: 전체 프로젝트 빌드 검증

기여하기

  1. 이슈를 생성하거나 기존 이슈를 확인하세요.
  2. 포크를 생성하고 새 브랜치를 만드세요.
  3. 변경사항을 구현하고 테스트하세요.
  4. 커밋 메시지를 명확하게 작성하세요.
  5. Pull Request를 생성하세요.

이슈 템플릿 사용하기

ExecuteJS 프로젝트는 버그 리포트와 기능 요청을 위한 GitHub 이슈 템플릿을 제공합니다. 이슈를 생성할 때 적절한 템플릿을 선택하여 작성해주시면 더 빠르고 정확한 피드백을 제공할 수 있습니다.

버그 리포트

버그를 발견하셨다면 "버그 리포트" 템플릿을 사용해주세요. 다음 정보를 포함해주시면 문제를 빠르게 해결할 수 있습니다:

  • 버그 설명: 버그에 대한 간단한 설명
  • 재현 단계: 버그를 재현하는 단계별 방법
  • 예상 동작: 정상적으로 동작했을 때 예상되는 결과
  • 실제 동작: 실제로 발생한 동작
  • 환경 정보: 운영체제, OS 버전, 앱 버전
  • 관련 코드: 버그와 관련된 JavaScript 코드 (선택사항)
  • 로그/에러 메시지: 콘솔 로그나 에러 메시지 (선택사항)
  • 스크린샷: 문제를 설명하는 스크린샷 (선택사항)

기능 요청

새로운 기능이나 개선 사항을 제안하고 싶으시다면 "기능 요청" 템플릿을 사용해주세요. 다음 정보를 포함해주시면 더 나은 제품을 만드는 데 도움이 됩니다:

  • 문제점 또는 개선이 필요한 부분: 이 기능이 해결하거나 개선할 문제점
  • 제안하는 해결 방법: 원하는 기능이나 개선 사항에 대한 구체적인 설명
  • 대안: 고려했던 다른 해결 방법 (선택사항)
  • 우선순위: 기능의 중요도 (낮음/보통/높음/매우 높음)
  • 관련 영역: 이 기능이 영향을 미치는 영역 (프론트엔드, 백엔드, JavaScript 런타임 등)
  • 사용 사례: 구체적인 사용 시나리오 (선택사항)
  • 목업/스크린샷: UI 변경이 포함된 경우 시각 자료 (선택사항)

이슈 생성 방법

  1. GitHub 저장소의 Issues 페이지로 이동합니다.
  2. "New issue" 버튼을 클릭합니다.
  3. "버그 리포트" 또는 "기능 요청" 템플릿을 선택합니다.
  4. 템플릿의 각 항목을 작성합니다.
  5. 이슈를 제출합니다.

커밋 컨벤션

type(scope): description feat: 새로운 기능 추가 fix: 버그 수정 docs: 문서 수정 style: 코드 포맷팅 refactor: 코드 리팩토링 test: 테스트 추가/수정 chore: 빌드 설정 변경

아키텍처

FSD (Feature-Sliced Design) 아키텍처

ExecuteJS 프론트엔드는 FSD 아키텍처를 사용하여 코드를 체계적으로 구성합니다.

폴더 구조

src/ ├── app/ # 앱 초기화 및 프로바이더 │ ├── index.tsx # 앱 루트 컴포넌트 │ └── providers.tsx # 전역 프로바이더 (Legend State, Radix UI) ├── pages/ # 페이지 레벨 컴포넌트 │ └── playground/ │ └── PlaygroundPage.tsx # 플레이그라운드 페이지 ├── widgets/ # 복합 UI 블록 │ ├── code-editor/ │ │ └── CodeEditor.tsx # Monaco Editor 래퍼 │ ├── output-panel/ │ │ └── OutputPanel.tsx # 출력 결과 패널 │ └── tab-bar/ │ └── TabBar.tsx # 탭 관리 UI ├── features/ # 비즈니스 로직 기능 │ ├── execute-code/ │ │ ├── model.ts # 실행 상태 및 로직 │ │ └── api.ts # Tauri command 호출 │ └── manage-tabs/ │ └── model.ts # 탭 관리 상태 (localStorage 연동) ├── shared/ # 공유 유틸리티 │ ├── ui/ # 공통 UI 컴포넌트 │ ├── lib/ # 유틸 함수 │ └── types/ # 공통 타입 └── main.tsx # Vite 엔트리

레이어별 역할

  • app/: 앱 초기화, 전역 프로바이더 설정
  • pages/: 페이지 레벨 컴포넌트 (라우팅 단위)
  • widgets/: 복합 UI 블록 (여러 features 조합)
  • features/: 비즈니스 로직 기능 (도메인별)
  • shared/: 공유 유틸리티 (재사용 가능)

의존성 규칙

  • 상위 레이어는 하위 레이어를 import 가능
  • 같은 레이어 내에서는 import 금지
  • shared는 다른 모든 레이어에서 import 가능

프론트엔드 기술 스택

  • 상태 관리: Zustand (경량 상태 관리)
  • UI 라이브러리: Radix UI + Tailwind CSS
  • 코드 에디터: Monaco Editor
  • 레이아웃: react-resizable-panels
  • 빌드 도구: Vite
  • 테스팅: Vitest + Testing Library
  • 린팅: oxlint + Prettier

백엔드 (Rust + Tauri)

  • 프레임워크: Tauri 2.0
  • JavaScript 엔진: Deno Core 0.323 (V8 기반)
  • npm 모듈 지원: npm 레지스트리에서 패키지를 직접 다운로드 및 사용
  • CommonJS 변환: CommonJS 패키지를 ES 모듈로 자동 변환(지원 예정)
  • UMD 변환: CommonJS 패키지를 ES 모듈로 자동 변환(지원 예정)
  • 테스팅: cargo test
  • 린팅: rustfmt
  • 로깅: tracing

npm 모듈 로딩 아키텍처

ExecuteJS는 커스텀 ModuleLoader를 구현하여 npm 패키지를 지원합니다:

  1. NpmModuleLoader: npm: 프로토콜을 처리하는 모듈 로더
  2. NpmResolver: npm 레지스트리에서 패키지를 다운로드하고 캐시
  3. CommonJS 변환: swc를 통해 CommonJS를 ES 모듈로 변환(지원 예정)
  4. UMD 변환: swc를 통해 UMD ES 모듈로 변환(지원 예정)
crates/deno-runtime/src/ ├── lib.rs # NpmModuleLoader 구현 └── npm_resolver.rs # npm 패키지 다운로드 및 캐시 관리

주요 기능:

  • npm 레지스트리 API를 통한 패키지 다운로드
  • 로컬 캐시를 통한 빠른 재사용
  • CommonJS, UMD → ES Module 자동 변환 (지원 예정)
  • 패키지 내부 상대 경로 import 지원

모노레포 구조

  • pnpm 워크스페이스: Node.js 패키지 관리
  • Cargo 워크스페이스: Rust 크레이트 관리
  • 조건부 CI: 폴더별 변경사항에 따른 워크플로우 실행

다음 단계

  • API 참조에서 사용 가능한 모든 Tauri 명령어를 확인하세요.
ON THIS PAGE