버전 v10에서 v11로 마이그레이션

pnpm v11은 설정을 읽는 방식과 사용 가능한 설정에 대한 여러 가지 주요 변경 사항을 도입합니다. 대부분의 설정 변경은 기계적이어서 codemod로 적용할 수 있으며, 나머지는 사람이 직접 확인해야 합니다. pnpm은 v10 설치에서 pnpm self-update 11이 실행되면 이 페이지에 대한 안내를 출력합니다.

Codemod 실행하기#

cd /path/to/your/project
pnpx codemod run pnpm-v10-to-v11
# or
pnpm add --global codemod
codemod run pnpm-v10-to-v11

해당 codemod는 다음 사항을 자동으로 적용합니다:

  • 설정을 package.json#pnpm에서 pnpm-workspace.yaml로 옮깁니다. 버전 v11에서 pnpm은 더 이상 package.json의 pnpm 필드에서 설정을 읽지 않습니다.
  • .npmrc를 인증/레지스트리 설정과 그 외 설정으로 분리합니다. v11은 .npmrc에서 인증 및 레지스트리 설정만 읽습니다. 그 외의 모든 설정(hoist-pattern, node-linker, save-exact, …) 은 camelCase 키로 pnpm-workspace.yaml에 옮겨집니다. 하위 프로젝트별 .npmrc 파일은 packageConfigs["<project-name>"] 아래에 배치됩니다.
  • 빌드 종속성 설정을 allowBuilds로 통합합니다. onlyBuiltDependencies, neverBuiltDependencies, ignoredBuiltDependencies, onlyBuiltDependenciesFile은 단일 allowBuilds 맵({ name: true | false })으로 병합됩니다.
  • 패키지 관리자 엄격성 설정을 pmOnFail로 대체합니다. managePackageManagerVersions, packageManagerStrict, packageManagerStrictVersion은 하나의 pmOnFail: download | ignore | warn | error 설정으로 통합됩니다.
  • allowNonAppliedPatches → allowUnusedPatches, auditConfig.ignoreCves → auditConfig.ignoreGhsas로 이름을 변경합니다 (키 이름만 변경되며, CVE ID는 여전히 수동으로 GHSA ID로 변환해야 합니다 — 아래 참조).
  • useNodeVersion을 루트 package.json의 devEngines.runtime 항목으로 변환합니다.
  • package.json의 packageManager를 대상 pnpm v11 버전으로 올립니다.

수동 후속 작업#

다음 변경 사항은 자동화할 수 없으므로 사람이 직접 확인해야 합니다:

  • CVE → GHSA. auditConfig.ignoreCves의 이름이 auditConfig.ignoreGhsas로 변경되었습니다. 각 CVE-YYYY-NNNNN 항목을 일치하는 GHSA-xxxx-xxxx-xxxx ID(pnpm audit 출력의 "More info" 열에 표시됨)로 바꾸세요.
  • **ignorePatchFailures**가 제거되었습니다. 이제 실패한 패치는 항상 오류를 발생시킵니다. 패치를 수정하거나 종속성을 제거하세요.
  • 워크스페이스 하위 패키지의 package.json#pnpm에 있는 **executionEnv.nodeVersion**이 제거되었습니다. 대신 해당 하위 패키지의 devEngines.runtime에 런타임을 선언하세요.
  • npm_config_* 환경 변수는 더 이상 읽지 않습니다. 이 변수가 설정된 모든 곳(CI 설정, 셸 프로필, Docker 이미지)에서 pnpm_config_*로 이름을 변경하세요.
  • **pnpm link <pkg-name>**은 더 이상 글로벌 스토어에서 패키지를 해석하지 않습니다. 상대 경로 또는 절대 경로(pnpm link ./foo)를 사용하세요.
  • pnpm install -g(인수 없이 실행)는 더 이상 지원되지 않습니다. 대신 pnpm add -g <pkg>을 사용하세요.
  • **pnpm server**는 대체 기능 없이 제거되었습니다.
  • 스크립트 이름이 내장 명령보다 우선합니다. package.json에 clean, setup, deploy 또는 rebuild라는 스크립트가 정의되어 있으면, 이제 pnpm <name>은 내장 명령 대신 해당 스크립트를 실행합니다. 내장 명령을 강제로 실행하려면 pnpm pm <name>을 사용하세요.

주요 변경 사항의 전체 목록은 v11 changelog를 참고하세요.