pnpm workspace와 filter로 패키지 실행하기

01폴더와 패키지 이름 나누기

폴더가 여러 개 있다는 이유만으로 workspace가 구성된 것은 아닙니다. 각 패키지의 package.json 이름과 루트의 경로 패턴을 확인하세요. 다음은 직접 만든 구조 예시입니다.

demo/
  pnpm-workspace.yaml
  package.json
  packages/
    ui/package.json       # name: @demo/ui
    app/package.json      # name: @demo/app

필터의 패키지 이름은 폴더 표시와 다를 수 있습니다. 같은 끝 이름을 가진 스코프 패키지가 여럿이면 전체 이름으로 지정하는 편이 모호함을 줄입니다.

02workspace 경로 선언

packages:
  - packages/*

이 예시는 packages 바로 아래 프로젝트를 포함합니다. 기존 YAML이 있다면 내용을 지우고 교체하지 말고 현재 패턴·설정을 먼저 읽으세요. 공식 문서의 v12.7.0 추가 안내는 YAML이 없을 때 루트 package.json의 workspaces를 변환하는 동작입니다. 기존 YAML은 덮어쓰지 않으며 버전이 다르면 이 자동 동작을 기대하면 안 됩니다.

03로컬 의존성은 workspace 프로토콜

가상의 @demo/app이 @demo/ui를 사용한다면 의존성을 다음처럼 지정할 수 있습니다.

{
  "dependencies": {
    "@demo/ui": "workspace:*"
  }
}

workspace:는 조건에 맞는 로컬 패키지로 해결하도록 요구합니다. 일반 버전 범위는 설정과 버전에 따라 레지스트리 패키지로 해결될 수 있으므로 같은 의미로 읽지 마세요. 로컬 패키지 이름이나 버전이 맞지 않는 오류를 임의의 외부 패키지 설치로 덮지 않습니다.

04filter의 두 방향 비교

pnpm --filter "@demo/app..." run build
pnpm --filter "...@demo/ui" run test

각 패키지에 해당 스크립트가 정의돼 있어야 합니다. 필터가 선택하는 범위와 빌드 시스템이 산출물·캐시를 관리하는 방식은 별개입니다. 명령이 끝났다는 표시만으로 배포 가능한 전체 결과를 만들었다고 가정하지 않습니다.

05자체 사례: 공통 UI를 바꾼 뒤 검사 대상

가상의 저장소에서 app이 ui를 사용한다고 가정합니다. ui 변경의 영향을 받는 app까지 검사하려면 의존하는 쪽을 선택하는 ...@demo/ui가 맞습니다. 반대로 app을 빌드할 준비물을 고를 때는 @demo/app... 방향입니다. 점 세 개의 위치가 결과를 바꾸는 것이 이 사례의 핵심입니다.

선택 대상이 없으면 경로 패턴·패키지 이름·현재 폴더·스코프를 확인하세요. 실제 workspace 생성·로컬 링크·패키지 설치·필터 실행·빌드 순서·배포는 이번에 실행하지 않았습니다. 공식 방향 규칙과 자체 두 패키지 관계를 검토한 안내입니다.

06목적별 가이드

07참고 자료

• pnpm workspace와 workspace 프로토콜
• pnpm filter 선택 방향
• pnpm 현재 버전·설치 안내