시작하기

설치

npm install -D lodestar @retemper/lodestar-plugin-architecture

설정 초기화

npx lodestar init

이 명령은 lodestar.config.ts를 생성합니다:

import { defineConfig } from '@retemper/lodestar';
import { pluginArchitecture } from '@retemper/lodestar-plugin-architecture';

export default defineConfig({
  plugins: [pluginArchitecture],
  rules: {
    'architecture/layers': {
      severity: 'error',
      options: {
        layers: [
          { name: 'domain', path: 'src/domain/**' },
          { name: 'application', path: 'src/application/**', canImport: ['domain'] },
          { name: 'infra', path: 'src/infra/**', canImport: ['domain', 'application'] },
        ],
      },
    },
  },
});

규칙 추가

rules 객체에서 규칙을 설정합니다. 각 규칙은 플러그인 네임스페이스로 접두사가 붙습니다:

export default defineConfig({
  plugins: [pluginArchitecture],
  rules: {
    // 전체 형식 -- 심각도 + 옵션
    'architecture/layers': {
      severity: 'error',
      options: {
        layers: [
          { name: 'domain', path: 'src/domain/**' },
          { name: 'application', path: 'src/application/**', canImport: ['domain'] },
        ],
      },
    },
    // 축약 형식 -- 심각도만
    'architecture/no-circular': 'error',
    // 모듈 캡슐화
    'architecture/modules': {
      severity: 'error',
      options: { modules: ['src/domain', 'src/billing'] },
    },
  },
});

검사 실행

npx lodestar check

출력:

  lodestar check

  ✗ architecture/layers
    Layer "domain" cannot import from "infra" — not listed in canImport
    at src/domain/entity.ts:5

  ✗ architecture/no-circular
    Circular dependency detected starting from "src/a.ts"
    at src/a.ts

  2 errors, 0 warnings

시각화

npx lodestar graph --layers

선언된 아키텍처를 실제 의존성 개수와 함께 Mermaid 다이어그램으로 보여줍니다. 위반 사항은 점선으로 표시됩니다.

CI에 추가

# .github/workflows/ci.yml
- run: npx lodestar check

심각도가 error인 위반이 있으면 0이 아닌 종료 코드를 반환합니다.

예제

examples/ 디렉토리에서 완전한 작동 프로젝트를 확인하세요:

• 클린 아키텍처 — Domain/Application/Infra 레이어와 ESLint, Prettier, Husky 어댑터
• 헥사고날 아키텍처 — Ports & Adapters 패턴의 Core/Adapters/Config 레이어

다음 단계

• 규칙(Rules) -- 규칙의 작동 방식
• 플러그인(Plugins) -- 공식 플러그인 살펴보기
• 설정(Configuration) -- 전체 설정 레퍼런스
• 워크스페이스 모드(Workspace Mode) -- 모노레포 지원