본문으로 건너뛰기
버전: 11 & 12

Node-Modules & Hoisting Settings

Node-Modules 설정​

modulesDir​

  • Default: node_modules
  • Type: path

The directory in which dependencies will be installed (instead of node_modules).

nodeLinker​

  • Default: isolated
  • Type: isolated, hoisted, pnp

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

  • isolated - dependencies are symlinked from a virtual store at node_modules/.pnpm.
  • hoisted - a flat node_modules without symlinks is created. Same as the node_modules created by npm or Yarn Classic. 이 설정을 사용하면 Yarn의 라이브러리 중 하나가 호이스팅에 사용됩니다. 이 설정을 사용해야 하는 정당한 이유:
    1. 여러분의 도구가 심볼릭 링크와 잘 작동하지 않습니다. A React Native project will most probably only work if you use a hoisted node_modules.
    2. 여러분의 프로젝트가 서버리스 호스팅 제공업체에 배포됩니다. 일부 서버리스 공급자 (예: AWS Lambda)는 심볼릭 링크를 지원하지 않습니다. 이 문제에 대한 대안 솔루션은 배포 전에 애플리케이션을 번들로 묶는 것입니다.
    3. If you want to publish your package with "bundledDependencies".
    4. If you are running Node.js with the --preserve-symlinks flag.
  • pnp - no node_modules. Plug'n'Play is an innovative strategy for Node that is used by Yarn Berry. It is recommended to also set symlink setting to false when using pnp as your linker.

nodeExperimentalPackageMap​

Added in: v11.8.0

  • Default: false
  • Type: Boolean

When true, pnpm injects the generated node_modules/.package-map.json into pnpm-managed Node.js script environments by adding Node's --experimental-package-map option to NODE_OPTIONS.

The package map is generated during isolated and hoisted installs. This setting only controls whether pnpm passes the generated map to scripts.

CLI and environment configuration use the kebab-case name node-experimental-package-map.

nodeExperimentalPackageMap: true

nodePackageMapType​

Added in: v11.8.0

  • Default: standard
  • Type: standard, loose

Controls how node_modules/.package-map.json is generated.

  • standard - only declared dependencies are available through the package map.
  • loose - also maps packages that are reachable through the installed node_modules layout, which can allow undeclared hoisted dependencies to resolve.

CLI and environment configuration use the kebab-case name node-package-map-type.

nodePackageMapType: loose
  • Default: true
  • Type: Boolean

When symlink is set to false, pnpm creates a virtual store directory without any symlinks. It is a useful setting together with nodeLinker=pnp.

enableModulesDir​

  • Default: true
  • Type: Boolean

When false, pnpm will not write any files to the modules directory (node_modules). 이것은 모듈 디렉토리가 사용자 공간 (FUSE) 의 파일 시스템으로 마운트될 때 유용합니다. There is an experimental CLI that allows you to mount a modules directory with FUSE: @pnpm/mount-modules.

virtualStoreDir​

  • Default: node_modules/.pnpm
  • Types: path

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

이것은 Windows에서 긴 경로 문제를 해결할 수 있는 유용한 설정입니다. If you have some dependencies with very long paths, you can select a virtual store in the root of your drive (for instance C:\my-project-store).

Or you can set the virtual store to .pnpm and add it to .gitignore. 이렇게 하면 의존성 경로가 한 디렉토리 더 높기 때문에 스택 트레이스를 더 깔끔하게 만들 수 있습니다.

NOTE: the virtual store cannot be shared between several projects. 모든 프로젝트에는 자체 가상 저장소가 있어야 합니다(루트가 공유되는 워크스페이스 제외).

virtualStoreDirMaxLength​

  • 기본값:
    • On Linux/macOS: 120
    • On Windows: 60
  • Types: number

Sets the maximum allowed length of directory names inside the virtual store directory (node_modules/.pnpm). You may set this to a lower number if you encounter long path issues on Windows.

virtualStoreOnly​

Added in: v11.0.0

  • Default: false
  • Type: Boolean

When set to true, pnpm populates the virtual store without creating importer symlinks, hoisting, bin links, or running lifecycle scripts. This is useful for pre-populating a store (e.g., in Nix builds) without creating unnecessary project-level artifacts. pnpm fetch uses this mode internally.

packageImportMethod​

  • Default: auto
  • Type: auto, hardlink, copy, clone, clone-or-copy

Controls the way packages are imported from the store (if you want to disable symlinks inside node_modules, then you need to change the nodeLinker setting, not this one).

  • auto - try to clone packages from the store. 복제가 지원되지 않으면 저장소에서 패키지를 하드링크합니다. 복제도, 연결도 불가능하면 복사로 대체합니다.
  • hardlink - hard link packages from the store
  • clone-or-copy - try to clone packages from the store. 복제가 지원되지 않으면 복사로 대체합니다.
  • copy - copy packages from the store
  • clone - clone (AKA copy-on-write or reference link) packages from the store

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

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

modulesCacheMaxAge​

  • Default: 10080 (7 days in minutes)
  • Type: number

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

dlxCacheMaxAge​

  • Default: 1440 (1 day in minutes)
  • Type: number

The time in minutes after which dlx cache expires. After executing a dlx command, pnpm keeps a cache that omits the installation step for subsequent calls to the same dlx command.

enableGlobalVirtualStore​

Added in: v10.12.1

  • Default: false
  • Type: Boolean
note

In pnpm v11, global installs (pnpm add -g) and pnpm dlx use the global virtual store by default.

When enabled, node_modules contains only symlinks to a central virtual store, rather than to node_modules/.pnpm. By default, this central store is located at <store-path>/links (use pnpm store path to find <store-path>).

In the central virtual store, each package is hard linked into a directory whose name is the hash of its dependency graph. As a result, all projects on the system can symlink their dependencies from this shared location on disk. This approach is conceptually similar to how NixOS manages packages, using dependency graph hashes to create isolated and shareable package directories in the Nix store.

This should not be confused with the global content-addressable store. The actual package files are still hard linked from the content-addressable store—but instead of being linked directly into node_modules/.pnpm, they are linked into the global virtual store.

Using a global virtual store can significantly speed up installations when a warm cache is available. However, in CI environments (where caches are typically absent), it may slow down installation. If pnpm detects that it is running in CI, this setting is automatically disabled.

important

To support hoisted dependencies when using a global virtual store, pnpm relies on the NODE_PATH environment variable. This allows Node.js to resolve packages from the hoisted node_modules directory. However, this workaround does not work with ESM modules, because Node.js no longer respects NODE_PATH when using ESM.

If your dependencies are ESM and they import packages not declared in their own package.json (which is considered bad practice), you’ll likely run into resolution errors. There are two ways to fix this:

  • Use packageExtensions to explicitly add the missing dependencies.
  • Add the @pnpm/plugin-esm-node-path config dependency to your project. This plugin registers a custom ESM loader that restores NODE_PATH support for ESM, allowing hoisted dependencies to be resolved correctly.

의존성 호이스팅 설정​

hoist​

  • Default: true
  • Type: boolean

When true, all dependencies are hoisted to node_modules/.pnpm/node_modules. This makes unlisted dependencies accessible to all packages inside node_modules.

hoistWorkspacePackages​

  • Default: true
  • Type: boolean

When true, packages from the workspaces are symlinked to either <workspace_root>/node_modules/.pnpm/node_modules or to <workspace_root>/node_modules depending on other hoisting settings (hoistPattern and publicHoistPattern).

hoistPattern​

  • Default: ['*']
  • Type: string[]

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

예를 들어:

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

You may also exclude patterns from hoisting using !.

예를 들어:

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

publicHoistPattern​

  • Default: []
  • Type: string[]

Unlike hoistPattern, which hoists dependencies to a hidden modules directory inside the virtual store, publicHoistPattern hoists dependencies matching the pattern to the root modules directory. 루트 모듈 디렉토리에 대한 호이스팅은 애플리케이션 코드가 해결 전략을 부적절하게 수정하더라도 유령 의존성에 액세스할 수 있음을 의미합니다.

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

예를 들어:

publicHoistPattern:
- "*plugin*"

Note: Setting shamefullyHoist to true is the same as setting publicHoistPattern to *.

You may also exclude patterns from hoisting using !.

예를 들어:

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

shamefullyHoist​

  • Default: false
  • Type: Boolean

By default, pnpm creates a semistrict node_modules, meaning dependencies have access to undeclared dependencies but modules outside of node_modules do not. 이 레이아웃을 사용하면 생태계의 대부분의 패키지가 문제 없이 작동합니다. However, if some tooling only works when the hoisted dependencies are in the root of node_modules, you can set this to true to hoist them for you.

hoistingLimits​

Added in: v11.5.0

  • Default: none
  • Type: none, workspaces, dependencies

Controls how far dependencies are hoisted when using nodeLinker: hoisted. This setting mirrors Yarn's nmHoistingLimits.

  • none - hoist as far as possible (the default).
  • workspaces - hoist only as far as each workspace package, preventing dependencies from being hoisted above the workspace package that depends on them.
  • dependencies - hoist only up to each workspace package's direct dependencies, preventing transitive dependencies from being hoisted into the workspace package's node_modules.