설정 (pnpm-workspace.yaml)

pnpm은 명령줄 옵션, 환경 변수, pnpm-workspace.yaml, .npmrc 파일에 정의된 설정값을 참조하여 동작합니다.

pnpm config 명령을 사용하면 프로젝트 단위 및 전역 설정 파일의 내용을 조회하거나 수정할 수 있습니다.

관련 설정 파일은 다음과 같습니다:

참고

인증 관련 설정은 .npmrc를 통해 처리됩니다.

설정 파일의 값은 ${NAME} 구문을 사용해 환경 변수를 포함할 수 있습니다. 환경 변수의 기본값을 지정할 수도 있습니다. ${NAME-fallback}을 사용하면 NAME이 설정되지 않은 경우 fallback을 반환합니다. ${NAME:-fallback}은 NAME이 설정되지 않았거나 빈 문자열인 경우 fallback을 반환합니다.

버전 v10.34.2부터 pnpm-workspace.yaml의 registry 설정에서는 환경 변수가 확장되지 않습니다. ${...} 자리 표시자가 포함된 값은 무시됩니다. 이유와 마이그레이션 옵션은 환경 변수를 참조하세요.

종속성 해석#

overrides#

이 필드를 사용하면 pnpm이 종속성 그래프 내의 모든 종속성을 재정의하도록 지시할 수 있습니다. 이 기능은 모든 패키지가 종속성의 단일 버전을 사용하도록 강제하거나, 수정 사항을 백포트하거나, 종속성을 포크로 대체하거나, 사용하지 않는 종속성을 제거할 때 유용합니다.

참고로, 재정의 필드는 프로젝트의 루트에서만 설정할 수 있습니다.

overrides 필드의 예시:

overrides:
  "foo": "^1.0.0"
  "quux": "npm:@myorg/quux@^1.0.0"
  "bar@^2.1.0": "3.0.0"
  "qar@1>zoo": "2"

패키지 선택자와 종속성 선택자를 ">"로 구분하여 오버라이드할 종속성이 속한 패키지를 지정할 수 있습니다. 예를 들어 qar@1>zoo는 qar@1의 zoo 종속성만 오버라이드하며, 다른 종속성에는 적용되지 않습니다.

재정의는 직접 종속성의 사양에 대한 참조로 정의될 수 있습니다. 이는 종속성 이름 앞에 $를 붙여서 수행합니다:

package.json
{
  "dependencies": {
    "foo": "^1.0.0"
  }
}
pnpm-workspace.yaml
overrides:
  foo: "$foo"

참조된 패키지는 대체된 패키지와 일치하지 않아도 됩니다.

pnpm-workspace.yaml
overrides:
  bar: "$foo"

특정 패키지를 사용할 때 해당 패키지의 종속성 중 하나가 필요하지 않다면 -를 사용하여 제거할 수 있습니다. 예를 들어 foo@1.0.0 패키지가 사용하지 않는 기능을 위해 bar라는 대형 패키지를 요구하는 경우, 이를 제거하면 설치 시간을 줄일 수 있습니다:

overrides:
  "foo@1.0.0>bar": "-"

이 기능은 대부분의 선택적 패키지를 안전하게 건너뛸 수 있는 optionalDependencies에서 특히 유용합니다.

packageExtensions#

packageExtensions 필드는 기존 패키지 정의를 추가 정보로 확장하는 방법을 제공합니다. 예를 들어 react-redux의 peerDependencies에 react-dom이 있어야 하지만 없는 경우, packageExtensions를 사용하여 react-redux를 패치할 수 있습니다:

packageExtensions:
  react-redux:
    peerDependencies:
      react-dom: "*"

packageExtensions의 키는 패키지 이름 또는 패키지 이름과 semver 범위이므로, 패키지의 일부 버전만 패치할 수 있습니다:

packageExtensions:
  react-redux@1:
    peerDependencies:
      react-dom: "*"

packageExtensions를 사용하여 확장할 수 있는 필드는 다음과 같습니다: dependencies, optionalDependencies, peerDependencies, peerDependenciesMeta.

더 큰 예시:

packageExtensions:
  express@1:
    optionalDependencies:
      typescript: "2"
  fork-ts-checker-webpack-plugin:
    dependencies:
      "@babel/core": "1"
    peerDependencies:
      eslint: ">= 6"
    peerDependenciesMeta:
      eslint:
        optional: true

팁

저희는 Yarn과 함께 생태계의 손상된 패키지를 패치하기 위한 packageExtensions 데이터베이스를 관리하고 있습니다. packageExtensions를 사용한다면 업스트림에 PR을 보내 확장을 @yarnpkg/extensions 데이터베이스에 기여하는 것을 고려해 주세요.

allowedDeprecatedVersions#

이 설정을 사용하면 특정 패키지의 사용 중단 경고를 끌 수 있습니다.

예시:

allowedDeprecatedVersions:
  express: "1"
  request: "*"

위 구성을 사용하면 pnpm은 request의 모든 버전과 express의 v1에 대한 사용 중단 경고를 출력하지 않습니다.

updateConfig#

updateConfig.ignoreDependencies#

때로는 종속성을 업데이트할 수 없는 경우가 있습니다. 예를 들어 최신 버전의 종속성이 ESM을 사용하기 시작했지만 프로젝트가 아직 ESM을 사용하지 않을 수 있습니다. 번거롭게도 이러한 패키지는 항상 pnpm outdated 명령에 출력되며, pnpm update --latest를 실행할 때 업데이트됩니다. 하지만 업그레이드하고 싶지 않은 패키지를 ignoreDependencies 필드에 나열할 수 있습니다:

updateConfig:
  ignoreDependencies:
  - load-json-file

패턴도 지원되므로 스코프의 모든 패키지를 무시할 수 있습니다: @babel/*.

supportedArchitectures#

설치를 실행 중인 시스템의 아키텍처와 일치하지 않더라도, 선택적 종속성을 설치하고자 하는 아키텍처를 지정할 수 있습니다.

예를 들어, 다음 구성은 Windows x64용 선택적 종속성을 설치하도록 지정합니다:

supportedArchitectures:
  os:
  - win32
  cpu:
  - x64

이 구성은 Windows, macOS 및 현재 설치를 실행 중인 시스템의 아키텍처에 대한 선택적 종속성을 설치합니다. 이 패키지에는 x64와 arm64 CPU용 아티팩트가 모두 포함되어 있습니다:

supportedArchitectures:
  os:
  - win32
  - darwin
  - current
  cpu:
  - x64
  - arm64

또한 supportedArchitectures는 시스템의 libc 지정도 지원합니다.

ignoredOptionalDependencies#

선택적 종속성의 이름이 이 배열에 포함되어 있으면 해당 종속성은 건너뜁니다. 예시:

ignoredOptionalDependencies:
- fsevents
- "@esbuild/*"

minimumReleaseAge#

버전 10.16.0에서 추가됨

  • 기본값: 0
  • 유형: number (minutes)

손상된 패키지를 설치할 위험을 줄이기 위해 새로 게시된 버전의 설치를 지연시킬 수 있습니다. 대부분의 경우 악성 릴리스는 한 시간 이내에 발견되어 레지스트리에서 제거됩니다.

minimumReleaseAge는 버전이 게시된 후 pnpm이 해당 버전을 설치하기까지 경과해야 하는 최소 분 수를 정의합니다. 이는 전이적 종속성을 포함한 모든 종속성에 적용됩니다.

예를 들어 다음 설정은 최소 하루 전에 릴리스된 패키지만 설치할 수 있도록 합니다:

minimumReleaseAge: 1440

minimumReleaseAgeExclude#

버전 10.16.0에서 추가됨

  • 기본값: undefined
  • 유형: string[]

minimumReleaseAge를 설정했지만 특정 종속성은 항상 최신 버전을 즉시 설치해야 하는 경우, 해당 종속성을 minimumReleaseAgeExclude에 나열할 수 있습니다. 제외는 패키지 이름 기준으로 동작하며 해당 패키지의 모든 버전에 적용됩니다.

예시:

minimumReleaseAge: 1440
minimumReleaseAgeExclude:
- webpack
- react

이 경우 webpack과 react를 제외한 모든 종속성은 최소 하루가 지나야 하며, 이 두 패키지는 릴리스 즉시 설치됩니다.

버전 10.17.0에서 추가됨

패턴을 사용할 수도 있습니다. 예를 들어 조직의 모든 패키지를 허용하려면 다음과 같이 합니다:

minimumReleaseAge: 1440
minimumReleaseAgeExclude:
- '@myorg/*'

버전 10.19.0에서 추가됨

특정 버전(또는 ||를 사용해 여러 버전을 나열한 목록)을 예외로 지정할 수도 있습니다. 이를 통해 최소 릴리스 경과 시간 규칙에 대한 예외를 특정 버전으로 고정할 수 있습니다:

minimumReleaseAge: 1440
minimumReleaseAgeExclude:
- nx@21.6.5
- webpack@4.47.0 || 5.102.1

trustPolicy#

버전 10.21.0에서 추가됨

  • 기본값: off
  • 유형: no-downgrade | off

이 설정을 no-downgrade로 설정하면 패키지의 신뢰 수준이 이전 릴리스에 비해 낮아진 경우 pnpm이 실패합니다. 예를 들어 패키지가 이전에는 신뢰할 수 있는 게시자에 의해 게시되었지만 현재는 출처 증명만 있거나 신뢰 증거가 없는 경우 설치가 실패합니다. 이는 침해되었을 가능성이 있는 버전의 설치를 방지하는 데 도움이 됩니다. 신뢰 검사는 semver가 아닌 게시 날짜만을 기준으로 합니다. 이전에 게시된 버전 중 하나라도 더 강력한 신뢰 증거를 가지고 있었다면 패키지를 설치할 수 없습니다. 버전 v10.24.0부터는 프리릴리스가 아닌 버전을 설치할 때 신뢰 증거를 평가하면서 프리릴리스 버전을 무시하므로, 신뢰할 수 있는 프리릴리스가 신뢰 증거가 없는 안정 릴리스를 차단하지 않습니다.

trustPolicyExclude#

버전 10.22.0에서 추가됨

  • 기본값: []
  • 유형: string[]

신뢰 정책 검사에서 제외할 패키지 선택자 목록입니다. 이를 통해 trustPolicy 요구 사항을 충족하지 않더라도 특정 패키지나 버전을 설치할 수 있습니다.

예시:

trustPolicy: no-downgrade trustPolicyExclude: - 'chokidar@4.0.3' - 'webpack@4.47.0 || 5.102.1' - '@babel/core@7.28.5'

trustPolicyIgnoreAfter#

버전 10.27.0에서 추가됨

  • 기본값: undefined
  • 유형: number (minutes)

지정한 분 수보다 오래 전에 게시된 패키지에 대해서는 신뢰 정책 검사를 무시할 수 있습니다. 이는 엄격한 신뢰 정책을 활성화할 때 유용합니다. 오래된 패키지 버전(서명이나 출처 증명을 사용한 게시 절차가 없을 수 있음)은 오래되었기 때문에 안전하다고 가정하고, 수동으로 제외하지 않아도 설치할 수 있게 해줍니다.

blockExoticSubdeps#

버전 10.26.0에서 추가됨

  • 기본값: false
  • 유형: Boolean

true로 설정하면 직접 종속성(루트 package.json에 나열된 종속성)만 이색 소스(git 저장소나 직접 tarball URL 등)를 사용할 수 있습니다. 모든 전이적 종속성은 구성된 레지스트리, 로컬 파일 경로, 워크스페이스 링크, 신뢰할 수 있는 GitHub 저장소(node, bun, deno) 등 신뢰할 수 있는 소스에서 해석되어야 합니다.

이 설정은 전이적 종속성이 신뢰할 수 없는 위치에서 코드를 가져오는 것을 방지하여 종속성 공급망을 보호하는 데 도움이 됩니다.

이색 소스에는 다음이 포함됩니다:

  • Git 저장소 (git+ssh://...)
  • 직접 tarball URL 링크 (https://.../package.tgz)

의존성 호이스팅 설정#

hoist#

  • 기본값: true
  • 유형: boolean

true이면 모든 종속성이 node_modules/.pnpm/node_modules로 호이스팅됩니다. 이렇게 하면 나열되지 않은 종속성에 node_modules 내부의 모든 패키지가 접근할 수 있습니다.

hoistWorkspacePackages#

  • 기본값: true
  • 유형: boolean

true이면 워크스페이스의 패키지가 다른 호이스팅 설정(hoistPattern 및 publicHoistPattern)에 따라 <workspace_root>/node_modules/.pnpm/node_modules 또는 <workspace_root>/node_modules에 심볼릭 링크됩니다.

hoistPattern#

  • 기본값: ['*']
  • 유형: string[]

node_modules/.pnpm/node_modules로 호이스팅할 패키지를 pnpm에 알려줍니다. 기본적으로 모든 패키지는 호이스팅됩니다, 하지만 유령 의존성을 갖는 잘못된 패키지를 알고 있다면 이 옵션을 이용해 유령 의존성을 호이스팅할 수 있습니다. (권장)

예를 들어:

hoistPattern:
- "*eslint*"
- "*babel*"

!를 사용하여 패턴을 호이스팅에서 제외할 수도 있습니다.

예를 들어:

hoistPattern:
- "*types*"
- "!@types/react"

publicHoistPattern#

  • 기본값: []
  • 유형: string[]

가상 스토어 내부의 숨겨진 모듈 디렉터리로 종속성을 호이스팅하는 hoistPattern과 달리, publicHoistPattern은 패턴과 일치하는 종속성을 루트 모듈 디렉터리로 호이스팅합니다. 루트 모듈 디렉토리에 대한 호이스팅은 애플리케이션 코드가 해결 전략을 부적절하게 수정하더라도 유령 의존성에 액세스할 수 있음을 의미합니다.

이 설정은 의존성을 제대로 해결하지 못하는 일부 결함이 있는 플러그형 도구를 처리할 때 유용합니다.

예를 들어:

publicHoistPattern:
- "*plugin*"

참고: shamefullyHoist를 true로 설정하는 것은 publicHoistPattern을 *로 설정하는 것과 같습니다.

!를 사용하여 패턴을 호이스팅에서 제외할 수도 있습니다.

예를 들어:

publicHoistPattern:
- "*types*"
- "!@types/react"

shamefullyHoist#

  • 기본값: false
  • 유형: Boolean

기본적으로 pnpm은 반엄격 node_modules를 생성합니다. 즉, 종속성은 선언되지 않은 종속성에 접근할 수 있지만 node_modules 외부의 모듈은 접근할 수 없습니다. 이 레이아웃을 사용하면 생태계의 대부분의 패키지가 문제 없이 작동합니다. 하지만 일부 도구가 호이스팅된 종속성이 node_modules 루트에 있을 때만 동작한다면, 이 값을 true로 설정하여 종속성을 호이스팅할 수 있습니다.

Node-Modules 설정#

modulesDir#

  • 기본값: node_modules
  • 유형: path

종속성이 설치될 디렉터리입니다(node_modules 대신).

nodeLinker#

  • 기본값: isolated
  • 유형: isolated, hoisted, pnp

노드 패키지 설치에 사용해야 하는 링커를 정의합니다.

  • isolated - 종속성이 node_modules/.pnpm의 가상 스토어에서 심볼릭 링크됩니다.
  • hoisted - 심볼릭 링크가 없는 평탄한 node_modules가 생성됩니다. 이는 npm 또는 Yarn Classic이 생성하는 node_modules와 같습니다. 이 설정을 사용하면 Yarn의 라이브러리 중 하나가 호이스팅에 사용됩니다. 이 설정을 사용해야 하는 정당한 이유:
    1. 여러분의 도구가 심볼릭 링크와 잘 작동하지 않습니다. React Native 프로젝트는 호이스팅된 node_modules를 사용해야만 동작할 가능성이 높습니다.
    2. 여러분의 프로젝트가 서버리스 호스팅 제공업체에 배포됩니다. 일부 서버리스 공급자 (예: AWS Lambda)는 심볼릭 링크를 지원하지 않습니다. 이 문제에 대한 대안 솔루션은 배포 전에 애플리케이션을 번들로 묶는 것입니다.
    3. "bundledDependencies"로 패키지를 게시하려는 경우.
    4. --preserve-symlinks 플래그로 Node.js를 실행하는 경우.
  • pnp - node_modules가 없습니다. Plug'n'Play는 Yarn Berry에서 사용하는 Node용 혁신적인 전략입니다. pnp를 링커로 사용할 때는 symlink 설정도 false로 지정하는 것이 좋습니다.

심볼릭 링크#

  • 기본값: true
  • 유형: Boolean

symlink가 false로 설정되면 pnpm은 심볼릭 링크가 없는 가상 스토어 디렉터리를 생성합니다. nodeLinker=pnp와 함께 사용하면 유용한 설정입니다.

enableModulesDir#

  • 기본값: true
  • 유형: Boolean

false이면 pnpm은 모듈 디렉터리(node_modules)에 어떤 파일도 쓰지 않습니다. 이것은 모듈 디렉토리가 사용자 공간 (FUSE) 의 파일 시스템으로 마운트될 때 유용합니다. FUSE로 모듈 디렉터리를 마운트할 수 있는 실험적인 CLI가 있습니다: @pnpm/mount-modules.

virtualStoreDir#

  • 기본값: node_modules/.pnpm
  • 유형: path

저장소에 대한 링크가 있는 디렉토리입니다. 프로젝트의 모든 직접 및 간접 의존성이 이 디렉토리에 연결됩니다.

이것은 Windows에서 긴 경로 문제를 해결할 수 있는 유용한 설정입니다. 경로가 매우 긴 종속성이 있다면 드라이브 루트에 있는 가상 스토어를 선택할 수 있습니다(예: C:\my-project-store).

또는 가상 스토어를 .pnpm으로 설정하고 .gitignore에 추가할 수 있습니다. 이렇게 하면 의존성 경로가 한 디렉토리 더 높기 때문에 스택 트레이스를 더 깔끔하게 만들 수 있습니다.

참고: 가상 스토어는 여러 프로젝트 간에 공유할 수 없습니다. 모든 프로젝트에는 자체 가상 저장소가 있어야 합니다(루트가 공유되는 워크스페이스 제외).

virtualStoreDirMaxLength#

  • 기본값:
    • Linux/macOS에서: 120
    • Windows에서: 60
  • 유형: number

가상 스토어 디렉터리(node_modules/.pnpm) 내 디렉터리 이름의 최대 허용 길이를 설정합니다. Windows에서 긴 경로 문제가 발생하면 이 값을 더 낮게 설정할 수 있습니다.

packageImportMethod#

  • 기본값: auto
  • 유형: auto, hardlink, copy, clone, clone-or-copy

스토어에서 패키지를 가져오는 방식을 제어합니다(node_modules 내부의 심볼릭 링크를 비활성화하려면 이 설정이 아니라 nodeLinker 설정을 변경해야 합니다).

  • auto - 스토어에서 패키지 복제를 시도합니다. 복제가 지원되지 않으면 저장소에서 패키지를 하드링크합니다. 복제도, 연결도 불가능하면 복사로 대체합니다.
  • hardlink - 스토어에서 패키지를 하드 링크합니다
  • clone-or-copy - 스토어에서 패키지 복제를 시도합니다. 복제가 지원되지 않으면 복사로 대체합니다.
  • copy - 스토어에서 패키지를 복사합니다
  • clone - 스토어에서 패키지를 복제(copy-on-write 또는 reference link라고도 함)합니다

node_modules에 패키지를 작성할 때 복제가 가장 좋은 방법입니다. 가장 빠르고 안전한 방법입니다. 복제를 사용하면 node_modules에서 파일을 편집할 수 있으며, 이는 중앙 content-addressable 저장소에서 수정되지 않습니다.

불행히도 모든 파일 시스템이 복제를 지원하는 것은 아닙니다. 최고의 pnpm 경험을 위해 CoW(Copy-On-Write) 파일 시스템(예: Linux에서 Ext4 대신 Btrfs)을 사용하는 것이 좋습니다.

modulesCacheMaxAge#

  • 기본값: 10080 (7일을 분으로 환산)
  • 유형: number

모듈 디렉토리에서 고아 패키지를 제거해야 하는 시간(분)입니다. pnpm은 모듈 디렉토리에 패키지 캐시를 유지합니다. 이렇게 하면 브랜치를 전환하거나 의존성을 다운그레이드할 때 설치 속도가 향상됩니다.

dlxCacheMaxAge#

  • 기본값: 1440 (1일을 분으로 환산)
  • 유형: number

캐시가 만료되기까지의 dlx 캐시 유지 시간을 분 단위로 지정합니다. 이후 동일한 dlx 명령을 호출할 때 설치 단계를 생략할 수 있도록, pnpm은 dlx 명령을 실행한 후 캐시를 유지합니다.

enableGlobalVirtualStore#

버전 10.12.1에서 추가됨

  • 기본값: false (CI에서는 항상 false)
  • 유형: Boolean
  • 상태: 실험적

활성화하면 node_modules에는 node_modules/.pnpm 대신 중앙 가상 스토어에 대한 심볼릭 링크만 포함됩니다. 기본적으로 이 중앙 스토어는 <store-path>/links에 있습니다(<store-path>를 찾으려면 pnpm store path를 사용하세요).

중앙 가상 스토어에서 각 패키지는 종속성 그래프의 해시를 이름으로 하는 디렉터리에 하드 링크됩니다. 결과적으로 시스템의 모든 프로젝트는 디스크의 이 공유 위치에서 종속성을 심볼릭 링크할 수 있습니다. 이 방식은 NixOS가 패키지를 관리하는 방식과 개념적으로 유사하며, 종속성 그래프 해시를 사용하여 Nix 스토어에 격리되고 공유 가능한 패키지 디렉터리를 생성합니다.

이는 전역 콘텐츠 주소 지정 스토어와 혼동해서는 안 됩니다. 실제 패키지 파일은 여전히 콘텐츠 주소 지정 스토어에서 하드 링크되지만, node_modules/.pnpm에 직접 링크되는 대신 전역 가상 스토어에 링크됩니다.

전역 가상 스토어를 사용하면 웜 캐시가 있을 때 설치 속도를 크게 높일 수 있습니다. 하지만 CI 환경(일반적으로 캐시가 없는 환경)에서는 설치 속도가 느려질 수 있습니다. 실행 환경이 CI임을 pnpm이 감지하면 이 설정은 자동으로 비활성화됩니다.

Important

전역 가상 스토어를 사용할 때 호이스팅된 종속성을 지원하기 위해 pnpm은 NODE_PATH 환경 변수를 사용합니다. 이를 통해 Node.js는 호이스팅된 node_modules 디렉터리에서 패키지를 해석할 수 있습니다. 하지만 Node.js는 ESM을 사용할 때 더 이상 NODE_PATH를 따르지 않으므로 이 해결 방법은 ESM 모듈에서는 동작하지 않습니다.

종속성이 ESM이고 자체 package.json에 선언되지 않은 패키지를 가져오는 경우(나쁜 관행으로 간주됨), 해석 오류가 발생할 가능성이 높습니다. 이를 해결하는 방법은 두 가지입니다:

  • packageExtensions를 사용하여 누락된 종속성을 명시적으로 추가합니다.
  • 프로젝트에 @pnpm/plugin-esm-node-path 구성 종속성을 추가합니다. 이 플러그인은 ESM에서 NODE_PATH 지원을 복원하는 사용자 정의 ESM 로더를 등록하여 호이스팅된 종속성이 올바르게 해석되도록 합니다.

스토어 설정#

storeDir#

  • 기본값:
    • $PNPM_HOME 환경 변수가 설정된 경우 $PNPM_HOME/store
    • $XDG_DATA_HOME 환경 변수가 설정된 경우 $XDG_DATA_HOME/pnpm/store
    • Windows에서: ~/AppData/Local/pnpm/store
    • macOS에서: ~/Library/pnpm/store
    • Linux에서: ~/.local/share/pnpm/store
  • 유형: path

모든 패키지가 저장되는 디스크 위치입니다.

저장소는 항상 설치가 발생하는 동일한 디스크에 있어야 합니다. 따라서 디스크당 하나의 저장소가 있도록 합니다. 현재 디스크에 홈 디렉토리가 있으면, 그 안에 저장소가 생성됩니다. 디스크에 홈이 없으면 파일 시스템의 루트에서 저장소가 생성됩니다. 예를 들어 /mnt에 마운트된 파일 시스템에서 설치가 진행되는 경우 스토어는 /mnt/.pnpm-store에 생성됩니다. Windows 시스템도 마찬가지입니다.

다른 디스크에서 저장소를 설정할 수 있지만, 이 경우 pnpm은 하드 링크 대신 저장소에서 패키지를 복사합니다. 하드 링크는 동일한 파일 시스템에서만 가능하기 때문입니다.

Important

이 pnpm 스토어는 서로 신뢰하는 사용자, 작업, 프로세스 간에만 공유하도록 설계되었습니다. 공유 storeDir을 구성하는 경우 신뢰할 수 없는 사용자가 쓸 수 없도록 파일 시스템 권한으로 보호하세요. 스토어는 pnpm의 신뢰 도메인에 속합니다. 패키지가 스토어에서 하드 링크될 수 있으며, 스토어 인덱스(index.db)에는 캐시된 파일을 검증하는 데 사용되는 해시가 기록됩니다.

verifyStoreIntegrity#

  • 기본값: true
  • 유형: Boolean

기본적으로 스토어의 파일이 수정된 경우, 해당 파일을 프로젝트의 node_modules에 링크하기 전에 파일 내용을 확인합니다. verifyStoreIntegrity가 false로 설정되면 설치 중에 콘텐츠 주소 지정 스토어의 파일을 확인하지 않습니다.

이 설정은 우발적인 스토어 손상을 감지하는 데 도움이 됩니다. 하지만 신뢰할 수 없는 사용자가 쓸 수 있는 스토어를 안전하게 만들어 주지는 않습니다. 스토어에 쓸 수 있는 공격자는 캐시된 패키지 내용과 이를 검증하는 데 사용되는 메타데이터를 모두 변경할 수 있기 때문입니다.

useRunningStoreServer#

위험

사용 중단된 기능

  • 기본값: false
  • 유형: Boolean

스토어 서버를 사용한 설치만 허용합니다. 실행 중인 스토어 서버가 없으면 설치가 실패합니다.

strictStorePkgContentCheck#

  • 기본값: true
  • 유형: Boolean

일부 레지스트리는 정확히 동일한 콘텐츠를 다른 패키지 이름 및/또는 버전으로 게시하는 것을 허용합니다. 이로 인해 스토어에 있는 패키지의 유효성 검사가 깨집니다. 스토어에서 이러한 패키지의 이름과 버전을 확인할 때 오류를 방지하려면 strictStorePkgContentCheck 설정을 false로 지정할 수 있습니다.

Lockfile 설정#

lockfile#

  • 기본값: true
  • 유형: Boolean

false로 설정하면 pnpm은 pnpm-lock.yaml 파일을 읽거나 생성하지 않습니다.

preferFrozenLockfile#

  • 기본값: true
  • 유형: Boolean

true로 설정되어 있고 사용 가능한 pnpm-lock.yaml이 package.json의 종속성 지시문을 충족하면 헤드리스 설치가 수행됩니다. 헤드리스 설치는 lockfile을 수정할 필요가 없기 때문에 모든 의존성 해결을 건너뜁니다.

lockfileIncludeTarballUrl#

  • 기본값: false
  • 유형: Boolean

pnpm-lock.yaml의 모든 항목에 패키지 tarball의 전체 URL을 추가합니다.

gitBranchLockfile#

  • 기본값: false
  • 유형: Boolean

true로 설정하면 병합 충돌을 완전히 피하기 위해 설치 후 생성되는 lockfile의 이름을 현재 브랜치 이름에 따라 지정합니다. 예를 들어 현재 브랜치 이름이 feature-foo이면 해당 lockfile 이름은 pnpm-lock.yaml 대신 pnpm-lock.feature-foo.yaml이 됩니다. 일반적으로 --merge-git-branch-lockfiles 명령줄 인수와 함께 사용하거나 pnpm-workspace.yaml 파일에 mergeGitBranchLockfilesBranchPattern을 설정하여 사용합니다.

mergeGitBranchLockfilesBranchPattern#

  • 기본값: null
  • 유형: Array or null

이 설정은 현재 분기 이름을 확인하여 모든 깃 브랜치의 lockfile을 병합할지 여부를 결정합니다. 기본적으로 --merge-git-branch-lockfiles 명령줄 매개변수를 수동으로 전달해야 합니다. 이 구성을 사용하면 이 프로세스가 자동으로 완료됩니다.

예를 들어:

mergeGitBranchLockfilesBranchPattern:
- main
- release*

!를 사용하여 패턴을 제외할 수도 있습니다.

peersSuffixMaxLength#

  • 기본값: 1000
  • 유형: number

종속성 키에 추가되는 피어 ID 접미사의 최대 길이이며, 이는 lockfile에 적용됩니다. 접미사가 더 길면 해시로 대체됩니다.

요청 설정#

gitShallowHosts#

  • 기본값: ['github.com', 'gist.github.com', 'gitlab.com', 'bitbucket.com', 'bitbucket.org']
  • 유형: string[]

Git 저장소인 종속성을 가져올 때 호스트가 이 설정에 나열되어 있으면 pnpm은 얕은 복제를 사용하여 전체 기록이 아닌 필요한 커밋만 가져옵니다.

networkConcurrency#

  • 기본값: auto (워커 수 × 3, 16~64 범위로 제한)
  • 유형: Number

동시에 처리할 HTTP(S) 요청의 최대 개수를 제어합니다.

버전 v10.24.0부터 pnpm은 워커 수에 따라 16에서 64 사이의 값을 자동으로 선택합니다(networkConcurrency = clamp(workers × 3, 16, 64)). 자동 조정을 재정의하려면 이 값을 명시적으로 설정하세요.

fetchRetries#

  • 기본값: 2
  • 유형: Number

레지스트리에서 가져오기에 pnpm이 실패한 경우 재시도할 횟수입니다.

fetchRetryFactor#

  • 기본값: 10
  • 유형: Number

재시도 백오프의 지수 계수입니다.

fetchRetryMintimeout#

  • 기본값: 10000 (10초)
  • 유형: Number

요청 재시도의 최소(기본) 타임아웃입니다.

fetchRetryMaxtimeout#

  • 기본값: 60000 (1분)
  • 유형: Number

재시도 계수로 인해 요청이 너무 길어지지 않도록 하는 최대 폴백 타임아웃입니다.

fetchTimeout#

  • 기본값: 60000 (1분)
  • 유형: Number

HTTP 요청이 완료될 때까지 기다리는 최대 시간입니다.

fetchWarnTimeoutMs#

버전 10.18.0에서 추가됨

  • 기본값: 10000 ms (10초)
  • 유형: Number

레지스트리에 대한 메타데이터 요청이 지정한 임곗값(밀리초)보다 오래 걸리면 경고 메시지가 표시됩니다.

fetchMinSpeedKiBps#

버전 10.18.0에서 추가됨

  • 기본값: 50 KiB/s
  • 유형: Number

레지스트리에서 tarball을 다운로드하는 속도가 지정한 임곗값(KiB/s) 아래로 떨어지면 경고 메시지가 표시됩니다.

피어 종속성 설정#

autoInstallPeers#

  • 기본값: true
  • 유형: Boolean

true이면 누락된 필수 피어 종속성이 모두 자동으로 설치됩니다.

버전 충돌#

서로 다른 패키지에서 피어 종속성에 대한 버전 요구 사항이 충돌하는 경우, pnpm은 충돌하는 피어 종속성의 어떤 버전도 자동으로 설치하지 않습니다. 대신 경고가 출력됩니다. 예를 들어 한 종속성은 react@^16.0.0을 요구하고 다른 종속성은 react@^17.0.0을 요구하면 요구 사항이 충돌하므로 자동 설치가 이루어지지 않습니다.

충돌 해결#

버전 충돌이 발생하면 어떤 버전의 피어 종속성을 설치할지 직접 판단하거나, 피어 종속성 요구 사항이 일치하도록 종속성을 업데이트해야 합니다.

dedupePeerDependents#

  • 기본값: true
  • 유형: Boolean

이 설정을 true로 지정하면 피어 해석 후 피어 종속성이 있는 패키지의 중복이 제거됩니다.

예를 들어 두 개의 프로젝트가 있는 워크스페이스에서 두 프로젝트 모두 종속성에 webpack이 있다고 가정해 보겠습니다. webpack은 선택적 피어 종속성에 esbuild가 있고, 프로젝트 중 하나는 종속성에 esbuild가 있습니다. 이 경우 pnpm은 node_modules/.pnpm 디렉터리에 webpack의 인스턴스 두 개를 링크합니다. 하나는 esbuild가 있고 다른 하나는 없습니다:

node_modules
  .pnpm
    webpack@1.0.0_esbuild@1.0.0
    webpack@1.0.0
project1
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0/node_modules/webpack
project2
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0_esbuild@1.0.0/node_modules/webpack
    esbuild

webpack은 두 프로젝트에서 사용되고 그중 한 프로젝트에는 esbuild가 없으므로, 두 프로젝트가 동일한 webpack 인스턴스를 공유할 수 없기 때문에 이는 타당합니다. 하지만 이는 대부분의 개발자가 기대하는 바가 아닙니다. 특히 호이스팅된 node_modules에서는 webpack의 인스턴스가 하나만 존재하기 때문입니다. 따라서 이제 dedupePeerDependents 설정을 사용하여 충돌하는 피어 종속성이 없을 때 webpack의 중복을 제거할 수 있습니다(설명은 마지막에 있습니다). 이 경우 dedupePeerDependents를 true로 설정하면 두 프로젝트 모두 동일한 webpack 인스턴스, 즉 esbuild가 해석된 인스턴스를 사용합니다:

node_modules
  .pnpm
    webpack@1.0.0_esbuild@1.0.0
project1
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0_esbuild@1.0.0/node_modules/webpack
project2
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0_esbuild@1.0.0/node_modules/webpack
    esbuild

충돌하는 피어 종속성이란 무엇인가요? 충돌하는 피어 종속성은 다음과 같은 시나리오를 의미합니다:

node_modules
  .pnpm
    webpack@1.0.0_react@16.0.0_esbuild@1.0.0
    webpack@1.0.0_react@17.0.0
project1
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0/node_modules/webpack
    react (v17)
project2
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0_esbuild@1.0.0/node_modules/webpack
    esbuild
    react (v16)

이 경우 webpack의 피어 종속성에 react가 있고 두 프로젝트의 컨텍스트에서 react가 서로 다른 두 버전으로 해석되므로 webpack의 중복을 제거할 수 없습니다.

strictPeerDependencies#

  • 기본값: false
  • 유형: Boolean

이 설정을 활성화하면 트리에 누락되었거나 유효하지 않은 피어 종속성이 있을 때 명령이 실패합니다.

resolvePeersFromWorkspaceRoot#

  • 기본값: true
  • 유형: Boolean

활성화하면 루트 워크스페이스 프로젝트의 종속성이 워크스페이스 내 모든 프로젝트의 피어 종속성을 해석하는 데 사용됩니다. 피어 종속성을 워크스페이스 루트에만 설치할 수 있고, 워크스페이스의 모든 프로젝트가 동일한 버전의 피어 종속성을 사용한다고 확신할 수 있으므로 유용한 기능입니다.

peerDependencyRules#

peerDependencyRules.ignoreMissing#

pnpm은 이 목록에 있는 누락된 피어 종속성에 대한 경고를 출력하지 않습니다.

예를 들어 다음 구성을 사용하면 종속성에 react가 필요하지만 react가 설치되어 있지 않을 때 pnpm이 경고를 출력하지 않습니다:

peerDependencyRules:
  ignoreMissing:
  - react

패키지 이름 패턴도 사용할 수 있습니다:

peerDependencyRules:
  ignoreMissing:
  - "@babel/*"
  - "@eslint/*"

peerDependencyRules.allowedVersions#

지정된 범위의 피어 종속성에 대해서는 충족되지 않은 피어 종속성 경고가 출력되지 않습니다.

예를 들어 react@16이 필요한 종속성이 있지만 react@17에서도 잘 동작한다는 것을 알고 있다면 다음 구성을 사용할 수 있습니다:

peerDependencyRules:
  allowedVersions:
    react: "17"

이렇게 하면 피어 종속성에 react가 있는 모든 종속성에서 react v17 설치를 허용해야 한다고 pnpm에 알립니다.

특정 패키지의 피어 종속성에 대해서만 경고를 표시하지 않도록 설정할 수도 있습니다. 예를 들어 다음 구성을 사용하면 react v17은 button v2 패키지의 피어 종속성에 있거나 card 패키지의 종속성에 있는 경우에만 허용됩니다:

peerDependencyRules:
  allowedVersions:
    "button@2>react": "17",
    "card>react": "17"

peerDependencyRules.allowAny#

allowAny는 패키지 이름 패턴의 배열로, 패턴과 일치하는 피어 종속성은 peerDependencies에 지정된 범위와 관계없이 모든 버전에서 해석됩니다. 예를 들어:

peerDependencyRules:
  allowAny:
  - "@babel/*"
  - "eslint"

위 설정은 @babel/ 패키지 또는 eslint와 관련된 피어 종속성 버전 불일치 경고를 모두 숨깁니다.

CLI 설정#

[no-]color#

  • 기본값: auto
  • 유형: auto, always, never

출력의 색상을 제어합니다.

  • auto - 표준 출력이 터미널 또는 TTY인 경우 출력에 색상을 사용합니다.
  • always - 터미널과 파이프의 차이를 무시합니다. 이 옵션이 필요한 경우는 드뭅니다. 대부분의 경우 리디렉션된 출력에 색상 코드를 넣고 싶다면 대신 pnpm 명령에 --color 플래그를 전달하여 색상 코드를 강제로 사용하게 할 수 있습니다. 기본 설정이 거의 항상 원하는 설정입니다.
  • never - 색상을 끕니다. --no-color에서 사용하는 설정입니다.

loglevel#

  • 기본값: info
  • 유형: debug, info, warn, error

지정한 수준 이상의 모든 로그가 표시됩니다. 대신 --silent를 전달하여 모든 출력 로그를 끌 수 있습니다.

useBetaCli#

  • 기본값: false
  • 유형: Boolean

CLI의 베타 기능을 활성화하는 실험적 옵션입니다. 즉, CLI 기능에 호환성을 깨는 변경 사항이나 잠재적인 버그가 생길 수 있습니다.

recursiveInstall#

  • 기본값: true
  • 유형: Boolean

이 설정을 활성화하면 pnpm install의 기본 동작이 pnpm install -r과 같아집니다. 즉, 모든 워크스페이스 또는 하위 디렉터리 패키지에서 설치가 수행됩니다.

그렇지 않으면 pnpm install은 현재 디렉터리의 패키지만 빌드합니다.

engineStrict#

  • 기본값: false
  • 유형: Boolean

이 설정을 활성화하면 pnpm은 현재 Node 버전과 호환되지 않는다고 명시한 패키지를 설치하지 않습니다.

이 설정과 관계없이 프로젝트(종속성 제외)가 engines 필드에 호환되지 않는 버전을 지정하면 설치는 항상 실패합니다.

npmPath#

  • 유형: path

게시와 같은 일부 작업에 pnpm이 사용하는 npm 바이너리의 위치입니다.

packageManagerStrict#

  • 기본값: true
  • 유형: Boolean

이 설정을 비활성화하면 package.json의 packageManager 필드에 다른 패키지 관리자가 지정되어 있어도 pnpm이 실패하지 않습니다. 활성화하면 패키지 이름만 확인하므로(pnpm v9.2.0부터) packageManager 필드에 지정된 버전과 관계없이 어떤 버전의 pnpm이든 실행할 수 있습니다.

또는 COREPACK_ENABLE_STRICT 환경 변수를 0으로 설정하여 이 설정을 비활성화할 수 있습니다.

packageManagerStrictVersion#

  • 기본값: false
  • 유형: Boolean

활성화하면 pnpm의 버전이 package.json의 packageManager 필드에 지정된 버전과 정확히 일치하지 않을 때 pnpm이 실패합니다.

managePackageManagerVersions#

  • 기본값: true
  • 유형: Boolean

활성화하면 pnpm은 package.json의 packageManager 필드에 지정된 pnpm 버전을 자동으로 다운로드하여 실행합니다. 이는 Corepack에서 사용하는 것과 동일한 필드입니다. 예시:

{
  "packageManager": "pnpm@9.3.0"
}

빌드 설정#

ignoreScripts#

  • 기본값: false
  • 유형: Boolean

프로젝트 package.json 및 해당 종속성에 정의된 스크립트를 실행하지 않습니다.

참고

이 플래그는 .pnpmfile.cjs의 실행을 막지 않습니다

ignoreDepScripts#

  • 기본값: false
  • 유형: Boolean

설치된 패키지의 스크립트를 실행하지 않습니다. 프로젝트의 스크립트는 실행됩니다.

참고

버전 v10부터 pnpm은 onlyBuiltDependencies에 나열되지 않은 종속성의 라이프사이클 스크립트를 실행하지 않습니다.

childConcurrency#

  • 기본값: 5
  • 유형: Number

동시에 할당할 수 있는 자식 프로세스의 최대 개수로, node_modules를 빌드하는 데 사용됩니다.

sideEffectsCache#

  • 기본값: true
  • 유형: Boolean

(pre/post)install 훅의 결과를 사용하고 캐시합니다.

설치 전후 스크립트가 패키지의 내용(예: 빌드 출력)을 수정하면 pnpm은 수정된 패키지를 전역 스토어에 저장합니다. 이후 같은 머신에서 설치할 때 pnpm은 캐시된 사전 빌드 버전을 재사용하여 설치 속도를 크게 높입니다.

참고

다음과 같은 경우 이 설정을 비활성화하는 것이 좋습니다:

  1. 설치 스크립트가 패키지 디렉터리 외부의 파일을 수정하는 경우(pnpm은 이러한 변경 사항을 추적하거나 캐시할 수 없습니다).
  2. 스크립트가 패키지 빌드와 관련 없는 부수 효과를 수행하는 경우.

sideEffectsCacheReadonly#

  • 기본값: false
  • 유형: Boolean

부수 효과 캐시가 있으면 사용만 하고, 새 패키지에 대해서는 생성하지 않습니다.

unsafePerm#

  • 기본값: root로 실행 중이면 false, 그렇지 않으면 true
  • 유형: Boolean

패키지 스크립트를 실행할 때 UID/GID 전환을 활성화하려면 true로 설정하세요. 명시적으로 false로 설정하면 root가 아닌 사용자로 설치할 때 실패합니다.

nodeOptions#

  • 기본값: NULL
  • 유형: String

NODE_OPTIONS 환경 변수를 통해 Node.js에 전달할 옵션입니다. 이는 pnpm 자체의 실행 방식에는 영향을 주지 않지만 라이프사이클 스크립트의 호출 방식에는 영향을 줍니다.

기존 NODE_OPTIONS를 유지하려면 구성에서 ${NODE_OPTIONS}를 사용하여 기존 환경 변수를 참조할 수 있습니다:

nodeOptions: "${NODE_OPTIONS:- } --experimental-vm-modules"

verifyDepsBeforeRun#

  • 기본값: false
  • 유형: install, warn, error, prompt, false

이 설정을 사용하면 스크립트를 실행하기 전에 종속성 상태를 확인할 수 있습니다. 이 검사는 pnpm run 및 pnpm exec 명령에서 실행됩니다. 지원되는 값은 다음과 같습니다:

  • install - node_modules가 최신 상태가 아니면 자동으로 설치를 실행합니다.
  • warn - node_modules가 최신 상태가 아니면 경고를 출력합니다.
  • prompt - node_modules가 최신 상태가 아니면 설치 실행 여부를 사용자에게 묻습니다.
  • error - node_modules가 최신 상태가 아니면 오류를 발생시킵니다.
  • false - 종속성 검사를 비활성화합니다.

strictDepBuilds#

버전 10.3.0에서 추가됨

  • 기본값: false
  • 유형: Boolean

strictDepBuilds가 활성화되어 있으면 검토되지 않은 빌드 스크립트(postinstall 스크립트라고도 함)가 있는 종속성이 하나라도 있을 때 설치가 오류 종료 코드로 종료됩니다.

allowBuilds#

버전 10.26.0에서 추가됨

스크립트 실행을 명시적으로 허용(true)하거나 허용하지 않을(false) 패키지 매처의 맵입니다. 이 필드는 onlyBuiltDependencies와 ignoredBuiltDependencies(이 새 설정으로 인해 사용 중단됨)를 대체하여 단일 정보 소스를 제공합니다.

allowBuilds:
  esbuild: true
  core-js: false
  nx@21.6.4 || 21.6.5: true

기본 동작: allowBuilds에 나열되지 않은 패키지는 기본적으로 허용되지 않으며 경고가 출력됩니다. strictDepBuilds가 true로 설정되어 있으면 대신 오류가 출력됩니다.

neverBuiltDependencies#

설치 중에 "preinstall", "install" 및/또는 "postinstall" 스크립트를 실행할 수 없는 패키지 이름 목록입니다.

onlyBuiltDependencies 없이 neverBuiltDependencies를 사용하면 다른 모든 종속성이 허용된다는 의미이므로 주의하세요.

neverBuiltDependencies 필드의 예시:

neverBuiltDependencies:
- fsevents
- level

onlyBuiltDependencies#

설치 중에 "preinstall", "install" 및/또는 "postinstall" 스크립트를 실행할 수 있는 패키지 이름 목록입니다. 이 배열에 나열된 패키지만 해당 라이프사이클 스크립트를 실행할 수 있습니다. onlyBuiltDependenciesFile과 neverBuiltDependencies를 생략하면 이 구성 옵션은 기본적으로 모든 설치 스크립트를 차단합니다.

예시:

onlyBuiltDependencies:
- fsevents

버전 10.19.0에서 추가됨

허용 범위를 특정 버전(또는 ||를 사용해 여러 버전을 나열한 목록)으로 제한할 수 있습니다. 버전을 지정하면 해당 버전의 패키지만 라이프사이클 스크립트를 실행할 수 있습니다:

onlyBuiltDependencies:
- nx@21.6.4 || 21.6.5
- esbuild@0.25.1

onlyBuiltDependenciesFile#

이 구성 옵션은 사용자가 pnpm 설치 과정에서 설치 스크립트를 실행할 수 있는 패키지만을 나열한 JSON 파일을 지정할 수 있도록 합니다. 이를 사용하여 보안을 강화하거나 설치 과정에서 특정 종속성만 스크립트를 실행하도록 할 수 있습니다.

예시:

configDependencies:
  '@pnpm/trusted-deps': 0.1.0+sha512-IERT0uXPBnSZGsCmoSuPzYNWhXWWnKkuc9q78KzLdmDWJhnrmvc7N4qaHJmaNKIusdCH2riO3iE34Osohj6n8w==
onlyBuiltDependenciesFile: node_modules/.pnpm-config/@pnpm/trusted-deps/allow.json

JSON 파일 자체에는 패키지 이름 배열이 포함되어야 합니다:

node_modules/.pnpm-config/@pnpm/trusted-deps/allow.json
[
  "@airbnb/node-memwatch",
  "@apollo/protobufjs",
  ...
]

ignoredBuiltDependencies#

버전 10.1.0에서 추가됨

설치 중에 "preinstall", "install" 및/또는 "postinstall" 스크립트를 실행할 수 없으며, 실행 여부에 대해 경고하거나 묻지 않을 패키지 이름 목록입니다.

라이프사이클 스크립트가 필요하지 않다는 것을 알고 있어서 경고를 숨기고 싶을 때 유용합니다.

예시:

ignoredBuiltDependencies:
- fsevents
- sharp

dangerouslyAllowAllBuilds#

버전 10.9.0에서 추가됨

  • 기본값: false
  • 유형: Boolean

true로 설정하면 종속성의 모든 빌드 스크립트(예: preinstall, install, postinstall)가 승인 없이 자동으로 실행됩니다.

경고

이 설정은 전이적 종속성을 포함한 모든 종속성이 현재와 미래 모두에 설치 스크립트를 실행할 수 있도록 허용합니다. 현재 종속성 그래프가 안전해 보이더라도:

  • 향후 업데이트로 신뢰할 수 없는 새로운 종속성이 추가될 수 있습니다.
  • 기존 패키지가 이후 버전에서 스크립트를 추가할 수 있습니다.
  • 패키지가 탈취되거나 손상되어 악성 코드를 실행하기 시작할 수 있습니다.

최대한의 안전을 위해 위험을 충분히 인지하고 가져오는 생태계 전체를 신뢰하는 경우에만 이 설정을 활성화하세요. 빌드를 검토하고 명시적으로 허용하는 것을 권장합니다.

Node.js 설정#

useNodeVersion#

  • 기본값: undefined
  • 유형: semver

프로젝트 런타임에 사용할 정확한 Node.js 버전을 지정합니다. pnpm은 지정된 버전의 Node.js를 자동으로 설치하고 pnpm run 명령이나 pnpm node 명령을 실행할 때 사용합니다.

.nvmrc와 nvm 대신 사용할 수 있습니다. 다음 .nvmrc 파일 대신:

16.16.0

이 pnpm-workspace.yaml 파일을 사용하세요:

useNodeVersion: 16.16.0

이 설정은 워크스페이스 루트에 있는 pnpm-workspace.yaml 파일에서만 동작합니다. 워크스페이스의 프로젝트에 사용자 정의 Node.js를 지정해야 하는 경우 대신 package.json의 executionEnv.nodeVersion 필드를 사용하세요.

nodeVersion#

  • 기본값: node -v가 반환하는 값, v 접두사 제외
  • 유형: 정확한 semver 버전(범위 아님)

패키지의 engines 설정을 확인할 때 사용할 Node.js 버전입니다.

프로젝트 기여자가 호환되지 않는 새 종속성을 추가하지 못하게 하려면 프로젝트 루트의 pnpm-workspace.yaml 파일에서 nodeVersion과 engineStrict를 사용하세요:

nodeVersion: 12.22.0
engineStrict: true

이렇게 하면 누군가 Node.js v16을 사용하더라도 Node.js v12.22.0을 지원하지 않는 새 종속성은 설치할 수 없습니다.

node-mirror#

  • 기본값: https://nodejs.org/download/<releaseDir>/
  • 유형: URL

Node.js를 다운로드할 기본 URL을 설정합니다. 이 설정의 <releaseDir> 부분은 https://nodejs.org/download의 모든 디렉터리가 될 수 있습니다: release, rc, nightly, v8-canary 등.

중국의 Node.js 미러에서 Node.js를 다운로드하도록 pnpm을 구성하는 방법은 다음과 같습니다:

node-mirror:release=https://npmmirror.com/mirrors/node/
node-mirror:rc=https://npmmirror.com/mirrors/node-rc/
node-mirror:nightly=https://npmmirror.com/mirrors/node-nightly/

executionEnv.nodeVersion#

프로젝트 런타임에 사용할 정확한 Node.js 버전을 지정합니다. pnpm은 지정된 버전의 Node.js를 자동으로 설치하고 pnpm run 명령이나 pnpm node 명령을 실행할 때 사용합니다.

예시:

executionEnv:
  nodeVersion: 16.16.0

기타 설정#

savePrefix#

  • 기본값: '^'
  • 유형: '^', '~', ''

package.json 파일에 설치된 패키지의 버전에 어떤 접두사를 붙일지 구성합니다.

예를 들어 패키지 버전이 1.2.3이면 기본적으로 버전이 ^1.2.3으로 설정되어 해당 패키지의 마이너 업그레이드를 허용하지만, pnpm config set save-prefix='~' 이후에는 ~1.2.3으로 설정되어 패치 업그레이드만 허용합니다.

추가된 패키지에 범위가 지정된 경우 이 설정은 무시됩니다. 예를 들어 pnpm add foo@2는 savePrefix 값과 관계없이 package.json의 foo 버전을 2로 설정합니다.

tag#

  • 기본값: latest
  • 유형: String

특정 버전을 지정하지 않고 pnpm add로 패키지를 추가하면 이 설정의 태그로 등록된 버전의 패키지가 설치됩니다.

또한 명시적인 태그가 주어지지 않은 경우 pnpm tag 명령으로 지정한 package@version에 추가되는 태그도 설정합니다.

globalDir#

  • 기본값:
    • $XDG_DATA_HOME 환경 변수가 설정된 경우 $XDG_DATA_HOME/pnpm/global
    • Windows에서: ~/AppData/Local/pnpm/global
    • macOS에서: ~/Library/pnpm/global
    • Linux에서: ~/.local/share/pnpm/global
  • 유형: path

전역 패키지를 저장할 사용자 정의 디렉터리를 지정합니다.

globalBinDir#

  • 기본값:
    • $XDG_DATA_HOME 환경 변수가 설정된 경우 $XDG_DATA_HOME/pnpm
    • Windows: ~/AppData/Local/pnpm
    • macOS: ~/Library/pnpm
    • Linux: ~/.local/share/pnpm
  • 유형: path

전역으로 설치된 패키지의 bin 파일이 위치할 대상 디렉터리를 설정할 수 있습니다.

stateDir#

  • 기본값:
    • $XDG_STATE_HOME 환경 변수가 설정된 경우 $XDG_STATE_HOME/pnpm
    • Windows: ~/AppData/Local/pnpm-state
    • macOS: ~/.pnpm-state
    • Linux: ~/.local/state/pnpm
  • 유형: path

업데이트 검사기에서만 현재 사용하는 pnpm-state.json 파일을 pnpm이 생성하는 디렉터리입니다.

cacheDir#

  • 기본값:
    • $XDG_CACHE_HOME 환경 변수가 설정된 경우 $XDG_CACHE_HOME/pnpm
    • Windows: ~/AppData/Local/pnpm-cache
    • macOS: ~/Library/Caches/pnpm
    • Linux: ~/.cache/pnpm
  • 유형: path

캐시(패키지 메타데이터, dlx 캐시, 일부 설치 검증 결과)의 위치입니다.

스토어와 마찬가지로 캐시 디렉터리는 서로 신뢰하는 사용자, 작업, 프로세스 간에만 공유하도록 설계되었습니다. 공유 cacheDir을 구성하거나 복원하는 경우 신뢰할 수 없는 사용자가 쓸 수 없도록 파일 시스템 권한으로 보호하세요.

useStderr#

  • 기본값: false
  • 유형: Boolean

값이 true이면 모든 출력이 stderr에 기록됩니다.

updateNotifier#

  • 기본값: true
  • 유형: Boolean

최신 버전보다 오래된 pnpm을 사용할 때 업데이트 알림을 표시하지 않으려면 false로 설정하세요.

preferSymlinkedExecutables#

  • 기본값: node-linker가 hoisted로 설정되어 있고 시스템이 POSIX인 경우 true
  • 유형: Boolean

node_modules/.bin에 명령 shim 대신 실행 파일에 대한 심볼릭 링크를 생성합니다. 명령 shim만 동작하는 Windows에서는 이 설정이 무시됩니다.

ignoreCompatibilityDb#

  • 기본값: false
  • 유형: Boolean

설치 중에 일부 패키지의 종속성이 자동으로 패치됩니다. 이를 비활성화하려면 이 설정을 true로 지정하세요.

패치는 Yarn의 @yarnpkg/extensions 패키지에서 적용됩니다.

resolutionMode#

  • 기본값: highest (v8.0.0부터 v8.6.12까지는 lowest-direct)
  • 유형: highest, time-based, lowest-direct

resolutionMode가 time-based로 설정되면 종속성은 다음과 같이 해석됩니다:

  1. 직접 종속성은 가장 낮은 버전으로 해석됩니다. 따라서 종속성에 foo@^1.1.0이 있으면 1.1.0이 설치됩니다.
  2. 하위 종속성은 마지막 직접 종속성이 게시되기 전에 게시된 버전에서 해석됩니다.

이 해석 모드를 사용하면 웜 캐시가 있는 설치가 더 빨라집니다. 또한 하위 종속성은 직접 종속성이 업데이트될 때만 업데이트되므로 하위 종속성 탈취 가능성도 줄어듭니다.

이 해석 모드는 npm의 full metadata에서만 동작합니다. 따라서 일부 시나리오에서는 더 느립니다. 하지만 Verdaccio v5.15.1 이상을 사용한다면 registrySupportsTimeField 설정을 true로 지정할 수 있으며, 이 경우 매우 빨라집니다.

resolutionMode가 lowest-direct로 설정되면 직접 종속성은 가장 낮은 버전으로 해석됩니다.

registrySupportsTimeField#

  • 기본값: false
  • 유형: Boolean

사용 중인 레지스트리가 축약된 메타데이터에서 "time" 필드를 반환한다면 이 값을 true로 설정하세요. 현재는 v5.15.1부터의 Verdaccio만 이를 지원합니다.

extendNodePath#

  • 기본값: true
  • 유형: Boolean

false이면 명령 shim에 NODE_PATH 환경 변수가 설정되지 않습니다.

deployAllFiles#

  • 기본값: false
  • 유형: Boolean

패키지를 배포하거나 로컬 패키지를 설치할 때 패키지의 모든 파일이 복사됩니다. 기본적으로 패키지의 package.json에 "files" 필드가 있으면 나열된 파일과 디렉터리만 복사됩니다.

dedupeDirectDeps#

  • 기본값: false
  • 유형: Boolean

true로 설정하면 워크스페이스의 루트 node_modules 디렉터리에 이미 심볼릭 링크된 종속성은 하위 프로젝트의 node_modules 디렉터리에 심볼릭 링크되지 않습니다.

optimisticRepeatInstall#

추가된 버전: v10.1.0

  • 기본값: false
  • 유형: Boolean

활성화하면 설치를 진행하기 전에 빠른 검사를 수행합니다. 이렇게 하면 반복 설치나 모든 것이 최신 상태인 프로젝트에서의 설치가 훨씬 빨라집니다.

requiredScripts#

이 배열에 나열된 스크립트는 workspace의 각 프로젝트에 필요합니다. 그렇지 않으면 pnpm -r run <script name>이 실패합니다.

requiredScripts:
- build

enablePrePostScripts#

  • 기본값: true
  • 유형: Boolean

true이면 pnpm은 모든 pre/post 스크립트를 자동으로 실행합니다. 따라서 pnpm foo를 실행하는 것은 pnpm prefoo && pnpm foo && pnpm postfoo를 실행하는 것과 같습니다.

scriptShell#

  • 기본값: null
  • 유형: path

pnpm run 명령으로 실행하는 스크립트에 사용할 셸입니다.

예를 들어, Windows에서 Git Bash를 사용하도록 강제하려면:

pnpm config set scriptShell "C:\\Program Files\\git\\bin\\bash.exe"

shellEmulator#

  • 기본값: false
  • 유형: Boolean

값이 true이면 pnpm은 bash-like shell의 JavaScript 구현을 사용하여 스크립트를 실행합니다.

이 옵션은 플랫폼 간 스크립팅을 단순화합니다. 예를 들어, 기본적으로 다음 스크립트는 POSIX 규격이 아닌 시스템에서 실패합니다:

"scripts": {
  "test": "NODE_ENV=test node test.js"
}

하지만 shellEmulator 설정을 true로 지정하면 모든 플랫폼에서 동작합니다.

참고

Node.js 22 이상에서는 pnpm의 도움 없이 스크립트를 실행할 수 있습니다. 위 예시의 경우 test 스크립트를 node --run test로 실행할 수 있습니다. 하지만 shellEmulator 옵션은 이 경우에 아무런 영향을 주지 않습니다. POSIX 기능에 의존하는 스크립트를 POSIX 규격이 아닌 환경에서 동작시키려면 pnpm run으로 실행해야 하며, node --run으로는 실행할 수 없습니다.

catalogMode#

버전 10.12.1에서 추가됨

  • 기본값: manual
  • 유형: manual, strict, prefer

pnpm add를 실행할 때 종속성을 기본 카탈로그에 추가할지 여부와 추가 방식을 제어합니다. 세 가지 모드가 있습니다:

  • strict - 카탈로그의 종속성 버전만 허용합니다. 카탈로그의 버전 범위를 벗어난 종속성을 추가하면 오류가 발생합니다.
  • prefer - 카탈로그 버전을 우선하지만, 호환되는 버전을 찾지 못하면 직접 종속성으로 대체합니다.
  • manual (기본값) - 종속성을 카탈로그에 자동으로 추가하지 않습니다.

ci#

버전 10.12.1에서 추가됨

  • 기본값: true (환경이 CI로 감지된 경우)
  • 유형: Boolean

이 설정은 현재 환경이 CI(지속적 통합) 환경인지 여부를 pnpm에 명시적으로 알려줍니다.

cleanupUnusedCatalogs#

버전 10.15.0에서 추가됨

  • 기본값: false
  • 유형: Boolean

값을 true로 설정하면 pnpm은 설치 중에 사용하지 않는 카탈로그 항목을 제거합니다.