package.json

패키지의 매니페스트 파일입니다. 여기에는 의존성, 제목, 작성자 등을 포함한 모든 패키지의 메타데이터가 포함됩니다. 이는 pnpm을 포함한 모든 주요 Node.js 패키지 관리자에서 유지되는 표준입니다.

In addition to the traditional package.json format, pnpm also supports package.json5 (in JSON5 format) and package.yaml (in YAML format).

참고

pnpm does not read settings from the pnpm field of package.json. Define settings in pnpm-workspace.yaml instead. 구성하기를 참조하세요.

bin#

The bin field maps command names to files inside the package. pnpm normalizes backslash separators to / and parent directory segments at the package root. For example, ../dist/cli.js resolves to dist/cli.js inside the package.

engines#

소프트웨어가 작동하는 Node 및 pnpm의 버전을 지정할 수 있습니다.

package.json
{
    "engines": {
        "node": ">=10",
        "pnpm": ">=3"
    }
}

If the project's engines.pnpm does not accept the running pnpm version, the install fails.

With engineStrict enabled, an incompatible engines.node in the project or in a dependency fails the install. Optional dependencies are exempt. With it disabled, an incompatible engines.node in the project or a required dependency prints a warning.

In a workspace, these checks apply to every workspace project, even when pnpm add or pnpm remove changes only one of them. pnpm run -r and pnpm exec -r run them too, before running anything. A project whose os, cpu, or libc excludes the current platform prints a warning.

A project's engines.node is checked against the first of these that applies:

  1. The nodeVersion setting, when it is set.
  2. The Node.js that pnpm downloads for the project through devEngines.runtime, or through engines.runtime when devEngines.runtime names no Node.js version: the pinned version, or the lowest version of a pinned range.
  3. The root project's runtime pin.
  4. The system Node.js.

--no-runtime skips the two runtime pins.

engines.runtime#

종속성에 필요한 Node.js 런타임을 지정합니다. 선언되면 pnpm은 지정된 Node.js 버전을 자동으로 설치합니다.

package.json
{
  "engines": {
    "runtime": {
      "name": "node",
      "version": "^24.11.0",
      "onFail": "download"
    }
  }
}

패키지가 런타임을 선언하면:

  1. CLI 앱의 경우: pnpm은 CLI를 필요한 Node.js 버전에 바인딩하여, 전역으로 설치된 Node.js 인스턴스와 관계없이 올바른 런타임을 사용하도록 합니다.
  2. postinstall 스크립트가 있는 패키지의 경우: 스크립트는 지정된 Node.js 버전을 사용하여 실행됩니다.

이는 올바르게 작동하기 위해 특정 Node.js 버전이 필요한 종속성에 특히 유용합니다.

devEngines.runtime#

프로젝트에서 사용하는 하나 이상의 JavaScript 런타임 엔진을 지정할 수 있습니다. 지원되는 런타임은 Node.js, Deno, Bun입니다.

예를 들어, 다음과 같이 종속성에 node@^24.4.0을 추가할 수 있습니다:

package.json
{
  "devEngines": {
    "runtime": {
      "name": "node",
      "version": "^24.4.0",
      "onFail": "download"
    }
  }
}

같은 package.json에 여러 런타임을 추가할 수도 있습니다:

package.json
{
  "devEngines": {
    "runtime": [
      {
        "name": "node",
        "version": "^24.4.0",
        "onFail": "download"
      },
      {
        "name": "deno",
        "version": "^2.4.3",
        "onFail": "download"
      }
    ]
  }
}

동작 방식:

  1. pnpm install은 지정한 범위를 일치하는 최신 런타임 버전으로 해석합니다.
  2. 정확한 버전(및 체크섬)이 lockfile에 저장됩니다.
  3. 스크립트는 로컬 런타임을 사용하므로 환경 간 일관성이 보장됩니다.

매니페스트를 수정하지 않고 선언된 onFail 동작을 재정의하려면 runtimeOnFail 설정을 사용하세요.

Since v12.0.0-rc.2, a bare node (or deno/bun) run from inside the project also follows this pin, not just scripts. This can be turned off with the globalShims setting, or skipped for a single command with PNPM_SHIM_BYPASS=1. See project-aware global bins.

packageManager#

Names the project's package manager and its exact version:

package.json
{
  "packageManager": "pnpm@12.0.0"
}

When a command runs with a different pnpm version, pnpm switches to the pinned one, as set by pmOnFail. To allow a range of versions, use devEngines.packageManager. See Package managers for other package managers.

devEngines.packageManager#

package.json의 devEngines.packageManager를 통해 pnpm 버전을 지정할 수 있습니다. packageManager 필드와 달리 버전 범위를 지원합니다. 해석된 버전은 pnpm-lock.yaml의 packageManagerDependencies 아래에 저장되며, 여전히 범위를 충족하는 경우 재사용됩니다.

When the lockfile records no version yet, pnpm records the running pnpm if it satisfies the range and was published at least minimumReleaseAge ago. Otherwise pnpm records the newest version in the range that is old enough. If no version in the range is old enough, pnpm records the running pnpm.

package.json
{
  "devEngines": {
    "packageManager": {
      "name": "pnpm",
      "version": ">=12.0.0 <13.0.0",
      "onFail": "download"
    }
  }
}

참고

When pnpm 12 is declared via the legacy packageManager field and pmOnFail is not set to ignore, its resolution info is written to pnpm-lock.yaml. The lockfile then gains a leading boot document.

Since v12.0.0-rc.6, the field can also name another package manager (npm, yarn or bun), which is what pnpm add npm@11 writes. For those, nothing is recorded in pnpm-lock.yaml: packageManagerDependencies holds pnpm's own pin, and another package manager is pinned in an environment lockfile of its own under the pnpm home.

매니페스트를 수정하지 않고 onFail 동작을 재정의하려면 pmOnFail 설정을 참조하세요.

dependenciesMeta#

dependencies, optionalDependencies 및 devDependencies에 선언된 종속성에 사용되는 추가 메타 정보입니다.

dependenciesMeta.*.injected#

로컬 워크스페이스 패키지인 종속성에 대해 이 값을 true로 설정하면, 해당 패키지는 가상 스토어(node_modules/.pnpm)에 하드 링크된 복사본을 생성하는 방식으로 설치됩니다.

이 값을 false로 설정하거나 설정하지 않으면, 대신 워크스페이스에 있는 패키지의 소스 디렉터리를 가리키는 node_modules 심볼릭 링크를 생성하는 방식으로 종속성이 설치됩니다. 이 방식이 더 빠르고 종속성의 변경 사항이 사용하는 쪽에 즉시 반영되므로 기본값입니다.

예를 들어, 다음 package.json이 로컬 워크스페이스 패키지라고 가정해 보겠습니다:

package.json
{
  "name": "card",
  "dependencies": {
    "button": "workspace:1.0.0"
  }
}

button 종속성은 일반적으로 card의 node_modules 디렉터리에 button의 개발 디렉터리를 가리키는 심볼릭 링크를 생성하는 방식으로 설치됩니다.

그런데 button이 peerDependencies에 react를 지정하면 어떻게 될까요? 모노레포의 모든 프로젝트가 동일한 버전의 react를 사용한다면 문제가 없습니다. 그런데 react@16을 사용하는 card와 react@17을 사용하는 form이 모두 button을 필요로 한다면 어떻게 될까요? 일반적으로는 react의 단일 버전을 선택하고 button의 devDependencies를 사용하여 지정해야 합니다. 심볼릭 링크는 card와 form 같은 서로 다른 소비자가 react 피어 종속성을 서로 다르게 충족할 수 있는 방법을 제공하지 않습니다.

injected 필드는 가상 스토어에 button의 하드 링크된 복사본을 설치하여 이 문제를 해결합니다. 이를 위해 card의 package.json을 다음과 같이 구성할 수 있습니다:

package.json
{
  "name": "card",
  "dependencies": {
    "button": "workspace:1.0.0",
    "react": "16"
  },
  "dependenciesMeta": {
    "button": {
      "injected": true
    }
  }
}

반면 form의 package.json은 다음과 같이 구성할 수 있습니다:

package.json
{
  "name": "form",
  "dependencies": {
    "button": "workspace:1.0.0",
    "react": "17"
  },
  "dependenciesMeta": {
    "button": {
      "injected": true
    }
  }
}

이러한 변경으로 button은 card와 form의 "주입된 종속성"이 됩니다. button이 react를 가져올 때, card의 컨텍스트에서는 react@16으로 해석되고 form의 컨텍스트에서는 react@17으로 해석됩니다.

주입된 종속성은 워크스페이스 소스 디렉터리의 복사본을 만들기 때문에, 코드가 수정될 때마다 이 복사본을 어떤 방식으로든 업데이트해야 합니다. 그렇지 않으면 새로운 상태가 사용하는 쪽에 반영되지 않습니다. pnpm --recursive run build와 같은 명령으로 여러 프로젝트를 빌드할 때, 이 업데이트는 각 주입된 패키지가 다시 빌드된 후, 그리고 해당 소비자가 다시 빌드되기 전에 이루어져야 합니다. 간단한 경우에는 pnpm install을 다시 실행하여 수행할 수 있으며, 해당 프로젝트 하나를 다시 빌드하기 위해 "prepare": "pnpm run build"와 같은 package.json 라이프사이클 스크립트를 사용할 수도 있습니다. The syncInjectedDepsAfterScripts setting refreshes the injected copies after the listed scripts run, and while they run. Third party tools such as pnpm-sync and pnpm-sync-dependencies-meta-injected also update injected dependencies, with watch mode support.

peerDependencies#

피어 종속성 값은 일반적으로 semver 범위(^1.0.0) 또는 workspace:나 catalog: 지정자입니다.

A peer dependency may also be declared with a specifier that carries a scheme:

package.json
{
  "peerDependencies": {
    "lib-a": "work:5.x.x",
    "lib-b": "npm:other-lib@^5",
    "lib-c": "file:../lib-c",
    "lib-d": "git+https://example.com/lib-d.git"
  }
}

허용되는 형식은 named-registry 사양(<registry>:<version>), npm: 별칭, 그리고 file:, git 또는 URL 사양입니다.

Such a specifier is matched against the semver range it carries: work:5.x.x is checked as 5.x.x and npm:other-lib@^5 as ^5. file:../lib-c와 같이 버전이 없는 지정자는 *와 비교되므로 어떤 버전이든 이를 충족합니다. 한편 autoInstallPeers가 누락된 피어를 설치할 때는 원래 지정자가 패키지를 선택하므로, 피어는 지정한 별칭 이름, 레지스트리 또는 소스에서 가져옵니다.

단순 name@version 값은 거의 항상 실수이므로 여전히 ERR_PNPM_INVALID_PEER_DEPENDENCY_SPECIFICATION과 함께 거부됩니다:

package.json
{
  "peerDependencies": {
    "lib-a": "lib-a@1.2.3"
  }
}

peerDependenciesMeta#

이 필드는 peerDependencies 필드에 나열된 종속성과 관련된 추가 정보를 지정합니다.

peerDependenciesMeta.*.optional#

이 값을 true로 설정하면 선택한 피어 종속성이 패키지 관리자에 의해 선택 사항으로 표시됩니다. 따라서 소비자가 이를 생략하는 경우 오류가 보고되지 않습니다."

예시:

package.json
{
    "peerDependencies": {
        "foo": "1"
    },
    "peerDependenciesMeta": {
        "foo": {
            "optional": true
        },
        "bar": {
            "optional": true
        }
    }
}

Even though bar was not specified in peerDependencies, it is marked as optional. 따라서 pnpm은 bar의 모든 버전이 괜찮다고 가정합니다. A missing foo causes no warning either, but an installed foo whose version does not satisfy 1 still produces a peer dependency warning.

publishConfig#

This field carries settings that change how a package is published: registry, access, directory, linkDirectory, executableFiles, and @<scope>:registry. These are preserved in the published package.json.

Additionally, publishConfig can be used to override several other fields in the manifest before the package is packed. 다음 필드를 재정의할 수 있습니다.

필드를 재정의하려면 해당 필드의 게시용 버전을 publishConfig에 추가하세요.

예를 들어, 다음 package.json은:

package.json
{
    "name": "foo",
    "version": "1.0.0",
    "main": "src/index.ts",
    "publishConfig": {
        "main": "lib/index.js",
        "typings": "lib/index.d.ts"
    }
}

다음과 같이 재정의 되어 게시됩니다.

package.json
{
    "name": "foo",
    "version": "1.0.0",
    "main": "lib/index.js",
    "typings": "lib/index.d.ts"
}

publishConfig.registry#

The registry this package publishes to. It overrides the registry setting, any scope route in registries, and pnpm publish --registry.

package.json
{
  "name": "foo",
  "version": "1.0.0",
  "publishConfig": {
    "registry": "https://registry.npmjs.org/"
  }
}

Only the URL belongs here. pnpm matches it against the auth settings in .npmrc, so the example above publishes with //registry.npmjs.org/:_authToken=....

Each package in a pnpm publish -r run goes to its own target registry, so one command can release a workspace to several registries. --batch then sends one request per registry.

Since v12.7.0, a scoped package can also set its registry under the @<scope>:registry key. For a package in that scope, it takes precedence over publishConfig.registry and over the registry set for the scope in .npmrc:

package.json
{
  "name": "@acme/foo",
  "version": "1.0.0",
  "publishConfig": {
    "@acme:registry": "https://npm.acme.example/"
  }
}

publishConfig.access#

Tells the registry whether the published package should be public or restricted. Same as pnpm publish --access.

Left unset, pnpm sends no access level, so the registry applies its own default and the level of an already published package is left alone. Unscoped packages cannot be restricted.

package.json
{
  "name": "@acme/foo",
  "version": "1.0.0",
  "publishConfig": {
    "access": "public"
  }
}

publishConfig.name#

워크스페이스의 매니페스트에 있는 이름과 다른 이름으로 패키지를 게시합니다. 이는 게시할 이름을 이미 형제 프로젝트가 사용하고 있어서, 그렇지 않으면 게시 직전에 빌드 단계에서 이름을 바꿔야 하는 프로젝트를 위한 것입니다.

package.json
{
  "name": "foo-v2",
  "version": "2.0.0",
  "publishConfig": {
    "name": "foo"
  }
}

Only the published artifact is renamed. Dependents, pnpm-lock.yaml, and release tooling keep addressing the project by its manifest name. 새 이름은 패킹된 매니페스트, tarball 파일 이름, 그리고 레지스트리에서 패키지를 참조하는 모든 것에 적용됩니다: pnpm publish -r의 이미 게시됨 확인 및 레지스트리 선택, 그리고 pnpm change status와 pnpm version -r의 릴리스 계획 확인이 이에 해당합니다.

publishConfig.executableFiles#

기본적으로, 이식성을 위해, bin 필드에 나열된 파일을 제외한 어떤 파일도 결과 패키지 아카이브에서 실행 가능한 것으로 표시되지 않습니다. executableFiles 필드를 사용하면 bin 필드를 통해 직접 접근할 수 없더라도 실행 플래그(+x)가 설정되어야 하는 추가 파일을 선언할 수 있습니다.

package.json
{
  "publishConfig": {
    "executableFiles": [
      "./dist/shim.js"
    ]
  }
}

publishConfig.directory#

publishConfig.directory 필드를 사용하여 현재 package.json을 기준으로 게시되는 하위 디렉터리를 사용자 지정할 수도 있습니다.

지정된 디렉터리에는 현재 패키지의 수정된 버전이 있어야 합니다(일반적으로 서드파티 빌드 도구를 사용합니다).

이 예시에서 "dist" 폴더에는 반드시 package.json이 있어야 합니다

package.json
{
  "name": "foo",
  "version": "1.0.0",
  "publishConfig": {
    "directory": "dist"
  }
}

publishConfig.linkDirectory#

  • 기본값: true
  • 유형: Boolean

true로 설정하면 로컬 개발 중에 프로젝트가 publishConfig.directory 위치에서 심볼릭 링크됩니다.

예시:

package.json
{
  "name": "foo",
  "version": "1.0.0",
  "publishConfig": {
    "directory": "dist",
    "linkDirectory": true
  }
}

publishConfig.variants#

  • Type: Array

Publishes the version as several archives, one per platform, to a registry declared with serverType: pnpr. pnpm installs the archive that fits the host. Each entry describes one archive:

  • targets: the platform tags the archive runs on, such as linux-x64, linux-x64-musl, darwin-arm64-macos_11_0, or win32-x64-napi8. The entry that targets any is the archive of every other host, the one npm and other clients install.
  • files: patterns of the files only this archive holds. Every file no entry claims goes into every archive.
  • manifest: fields that replace the package's fields in this archive's package.json. null removes a field.
package.json
{
  "name": "example-cli",
  "version": "4.0.0",
  "bin": { "example-cli": "bin/example-cli.js" },
  "publishConfig": {
    "variants": [
      { "targets": ["any"], "files": ["lib/**"] },
      {
        "targets": ["linux-x64", "linux-x64-musl"],
        "files": ["native/linux-x64/example-cli"],
        "manifest": { "bin": { "example-cli": "native/linux-x64/example-cli" } }
      }
    ]
  }
}

A platform variant is named by its targets, sorted and joined with +, such as linux-x64+linux-x64-musl. A target appears in one entry only. Without an any entry, the version has no archive for other hosts, and installing it there fails. A platform variant can't run install scripts or have a binding.gyp, and an entry's manifest can't set name, version, or peer dependencies.