2계층 폴더 구조

GS Retail Nx 모노레포의 표준 레이아웃입니다. 앱과 라이브러리를 명확히 분리합니다.

타입 접미사 규칙

태그와 모듈 경계

각 라이브러리의 project.json에 scope 태그와 type 태그를 반드시 붙입니다.

// libs/web/feature-checkout/project.json
{
  "name": "web-feature-checkout",
  "tags": ["scope:web", "type:feature"]
}

@nx/enforce-module-boundaries 설정

ESLint 규칙으로 경계를 강제합니다. .eslintrc.json 또는 eslint.config.mjs에 적용:

{
  "@nx/enforce-module-boundaries": ["error", {
    "allow": [],
    "depConstraints": [
      // 같은 scope끼리만 의존 가능
      {
        "sourceTag": "scope:web",
        "onlyDependOnLibsWithTags": ["scope:web", "scope:shared"]
      },
      {
        "sourceTag": "scope:admin",
        "onlyDependOnLibsWithTags": ["scope:admin", "scope:shared"]
      },
      // 타입 방향성: feature → data-access → util
      {
        "sourceTag": "type:feature",
        "onlyDependOnLibsWithTags": ["type:feature", "type:data-access", "type:ui", "type:util"]
      },
      {
        "sourceTag": "type:data-access",
        "onlyDependOnLibsWithTags": ["type:data-access", "type:util"]
      },
      {
        "sourceTag": "type:ui",
        "onlyDependOnLibsWithTags": ["type:ui", "type:util"]
      },
      {
        "sourceTag": "type:util",
        "onlyDependOnLibsWithTags": ["type:util"]
      }
    ]
  }]
}

TypeScript 프로젝트 참조

Nx 워크스페이스에서 경로 별칭(path alias) 대신 TypeScript 프로젝트 참조를 우선합니다. 증분 빌드(incremental build)를 활성화해 빌드 속도를 높입니다.

// libs/web/util-format/tsconfig.json
{
  "extends": "../../../tsconfig.base.json",
  "compilerOptions": {
    "composite": true,          // 프로젝트 참조 필수
    "incremental": true,        // 증분 빌드
    "declaration": true,
    "declarationMap": true
  }
}

// tsconfig.base.json (workspace root)
{
  "compilerOptions": {
    "paths": {
      "@myorg/web/util-format": ["libs/web/util-format/src/index.ts"]
    }
  }
}

// 프로젝트 참조 추가 (tsconfig.json 참조 배열)
{
  "references": [
    { "path": "../../../libs/web/util-format" }
  ]
}

플러그인 Executor

규칙: 프레임워크 네이티브 executor(@nx/next, @nx/react)를 원시 nx:run-commands보다 우선합니다.

// apps/web/project.json — 올바른 방식
{
  "targets": {
    "build": {
      "executor": "@nx/next:build",    // ✅ 프레임워크 플러그인
      "options": { "outputPath": "dist/apps/web" }
    },
    "serve": {
      "executor": "@nx/next:server",   // ✅
      "options": { "buildTarget": "web:build" }
    }
  }
}

// ❌ 피해야 할 방식
{
  "targets": {
    "build": {
      "executor": "nx:run-commands",
      "options": { "commands": ["next build"] }  // raw command
    }
  }
}

명령어 표면

affected 활용 팁

# PR 기준으로 affected 계산
nx affected -t build --base=main --head=HEAD

# 특정 브랜치 대비
nx affected -t test --base=origin/main

# verbose 출력
nx affected -t build --verbose

안티패턴 체크리스트

• ✗ 내부 파일 직접 import: import from '@myorg/lib/src/components/Foo' → 반드시 index.ts를 통해 공개된 API만 사용
• ✗ 순환 의존성: A→B→A 구조. nx graph로 주기적 확인
• ✗ 태그 없는 라이브러리: project.json에 tags 없으면 경계 규칙이 적용되지 않음
• ✗ apps/ 에서 apps/ 직접 import: 앱 간 공유는 반드시 libs/shared/ 경유
• ✗ packages/ 에 내부 전용 코드: packages/는 외부 npm 배포 전용
• ✗ nx:run-commands 남발: 프레임워크 플러그인이 있는데 raw command 사용 금지
• ✗ 모든 것을 feature lib으로: 유틸리티는 util, 스토어는 data-access로 분리
• ✗ 경계 위반 무시: ESLint 경고를 // eslint-disable로 무력화 금지

Claude와 Nx 작업 플로우

Agent에게 Nx 관련 작업을 요청할 때 nx-best-practices 스킬이 자동 로드됩니다.

# 새 feature lib 생성 요청 예시
"웹 앱에 장바구니 feature lib 만들어줘"
→ Agent가 nx g @nx/react:lib web/feature-cart 실행
→ project.json에 tags: ["scope:web", "type:feature"] 자동 추가
→ tsconfig.base.json 경로 별칭 등록
→ enforce-module-boundaries 준수 확인