본문으로 건너뛰기
버전: Next

package.json

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

engines​

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

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

로컬 개발 중에 버전이 engines 필드에 지정된 버전과 일치하지 않으면 pnpm은 항상 오류 메시지와 함께 실패합니다.

사용자가 engine-strict 구성 플래그를 설정하지 않은 경우( .npmrc참조), 이 필드는 권고 사항일 뿐이며 패키지가 의존성으로 설치된 경우에만 경고를 생성합니다.

dependenciesMeta​

dependencies, optionalDependencies 및 devDependencies 내부에 선언된 종속성을 위한 추가적인 메타 정보입니다.

dependenciesMeta.*.injected​

로컬 의존성에 대해 true로 설정되면, 패키지는 심볼릭 링크가 아닌 모듈 디렉토리에 하드 링크됩니다.

예를 들어, 워크스페이스의 다음 package.json 은 card의 node_modules 디렉토리에 있는 button 에 대한 심볼릭 링크를 생성합니다.

{
  "name": "card",
  "dependencies": {
    "button": "workspace:1.0.0"
  }
}

그러나 button 의 피어 의존성에 react 이 있으면 어떻게 될까요? monorepo의 모든 프로젝트가 동일한 버전의 react 를 사용하면 문제가 없습니다. 그러나, react@16을 사용하는 card와 react@17을 사용하는 form를 button이 필요하다면 어떻게 될까요? inject을 사용하지 않고, react 의 단일 버전을 선택하고 button의 개발 의존성으로 설치해야 합니다. 그러나 inject 필드를 사용하면, button 을 패키지에 주입할 수 있으며, button 은 해당 패키지의 react 버전과 함께 설치됩니다.

그래서 이것은 card 의 package.json 이 됩니다.

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

button은 card의 의존성에 하드 링크되고, react@16은 card/node_modules/button의 의존성에 심볼릭 링크됩니다.

그래서 이것은 card의 package.json이 됩니다.

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

button은 form의 의존성에 하드 링크되고, react@17은 card/node_modules/button의 의존성에 심볼릭 링크됩니다.

일반적인 종속성과는 달리, 삽입된 종속성은 대상 폴더에 심볼릭 링크로 연결되지 않으므로 빌드 스크립트 실행 후에도 자동으로 업데이트되지 않습니다. 하드 링크된 폴더 내용을 종속성 패키지의 폴더의 최신 상태로 업데이트 하려면 pnpm i를 다시 호출 해야 합니다.

button 패키지는 설치 시 실행되는 라이프사이클 스크립트가 있어야만 pnpm이 변경 사항을 감지하고 업데이트할 수 있습니다. 예를 들어, 패키지를 빌드 하기 위해선 "prepare":"pnpm run build" 를 실행하여야 합니다. 다음과 같이 외부에 영향을 주지 않는 간단한 관련 없는 명령이라도 모든 스크립트가 작동합니다. "prepare":"pnpm root".

peerDependenciesMeta​

이 필드는 peerDependencies 필드에 작성된 의존성과 관련된 몇 가지 추가 정보를 나타냅니다.

peerDependenciesMeta.*.optional​

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

예시:

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

peerDependencies에 bar가 지정되지 않았더라도, optional로 표시됩니다. 따라서 pnpm은 bar의 모든 버전이 괜찮다고 가정합니다. 그러나 foo는 optional이지만 필수 버전 사양에만 해당됩니다.

publishConfig​

패키지가 압축되기 전에 manifest 내부에 선언된 일부 필드들을 재정의 할 수 있습니다. 다음 필드를 재정의할 수 있습니다.

필드를 재정의하려면 필드의 게시 버전을 publishConfig에 추가합니다.

예를 들어, package.json은 다음과 같습니다.

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

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

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

publishConfig.executableFiles​

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

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

publishConfig.directory​

또한 필드 publishConfig.directory를 사용하여 현재 package.json을 기준으로 게시된 하위 디렉터리를 커스터마이징 할 수 있습니다.

지정된 디렉토리에 현재 패키지의 수정된 버전이 있을 때 사용할 수 있습니다. (일반적으로 써드파트 도구를 사용할 때)

이 예시에서 "dist" 폴더에는 package.json이 포함되어야 합니다.

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

publishConfig.linkDirectory​

  • 기본값: true
  • 유형: Boolean

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

예시:

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

pnpm.overrides​

이 필드를 사용하면 pnpm이 의존성 그래프 내의 의존성을 재정의하도록 지시할 수 있습니다. 이는 모든 패키지가 동일한 종속성 버전을 사용하도록 강제하거나 수정 사항을 역포팅(backport) 하거나 종속성을 대체(fork) 하는 데 유용합니다.

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

"pnpm"."overrides" 필드의 예시:

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

대체될 종속성이 속한 패키지를 지정하려면 package selector와 dependency selector를 ">"로 구분하면 됩니다. 예를 들어 qar@1>zoo는 qar@1의 zoo 종속성만을 대체하며, 다른 종속성에는 영향을 주지 않습니다.

재정의는 직접 종속성의 사양에 대한 참조로 정의될 수 있습니다. 이는 종속성 이름 앞에 $접두사를 추가하여 수행됩니다.

{
  "dependencies": {
    "foo": "^1.0.0"
  },
  "pnpm": {
    "overrides": {
      "foo": "$foo"
    }
  }
}

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

{
  "dependencies": {
    "foo": "^1.0.0"
  },
  "pnpm": {
    "overrides": {
      "bar": "$foo"
    }
  }  
}

pnpm.packageExtensions​

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

{
  "pnpm": {
    "packageExtensions": {
      "react-redux": {
        "peerDependencies": {
          "react-dom": "*"
        }
      }
    }
  }
}

packageExtensions의 키는 패키지 이름이거나 패키지 이름 및 semver 범위임에 따라, 패키지의 일부 버전만 패치할 수 있습니다.

{
  "pnpm": {
    "packageExtensions": {
      "react-redux@1": {
        "peerDependencies": {
          "react-dom": "*"
        }
      }
    }
  }
}

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

더 큰 예시:

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

Yarn과 함께 우리는 생태계에서 손상된 패키지를 수정하기 위해 packageExtensions 데이터베이스를 유지 관리합니다. 만약 packageExtensions을 사용한다면, @yarnpkg/extensions 데이터베이스에 기여하여 PR을 보내는 것을 고려해보세요.

pnpm.peerDependencyRules​

pnpm.peerDependencyRules.ignoreMissing​

pnpm은 이 목록에서 누락된 peer dependencies 대한 경고를 출력하지 않습니다.

예를 들어, 다음 구성에서 pnpm은 의존성에 react 가 필요하지만 react가 설치되지 않은 경우 경고를 출력하지 않습니다.

{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["react"]
    }
  }
}

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

{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["@babel/*", "@eslint/*"]
    }
  }
}

pnpm.peerDependencyRules.allowedVersions​

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

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

{
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": {
        "react": "17"
      }
    }
  }
}

이것은 peer Dependency 에 react를 갖고 있는 모든 의존성이 react v17 설치를 허용해야 함을 pnpm에 알려줍니다.

특정 패키지의 peer Dependencies에 대해서만 경고를 표시하지 않을 수도 있습니다. 예를 들어 다음 구성에서 react v17은 button v2 패키지의 peer dependencies 또는 card 패키지의 dependencies에 있는 경우에만 허용됩니다.

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

pnpm.peerDependencyRules.allowAny​

allowAny은 패키지 이름 패턴의 배열이며, 패턴과 일치하는 모든 peer dependency은 peerDependencies에 지정된 범위에 관계없이 모든 버전에서 확인됩니다. 예를 들어:

{
  "pnpm": {
    "peerDependencyRules": {
      "allowAny": ["@babel/*", "eslint"]
    }
  }
}

위의 설정은 @babel/ 패키지 또는 eslint와 관련된 peer dependency에 버전 불일치 경고를 끕니다.

pnpm.neverBuiltDependencies​

이 필드를 사용하면 특정 의존성의 빌드를 무시할 수 있습니다. 나열된 패키지의 "preinstall", "install" 및 "postinstall" 스크립트는 설치 중에 실행되지 않습니다.

"pnpm"."neverBuiltDependencies" 필드의 예시:

{
  "pnpm": {
    "neverBuiltDependencies": ["fsevents", "level"]
  }
}

pnpm.onlyBuiltDependencies​

설치 중에 실행할 수 있는 패키지 이름 목록입니다. 이 필드가 있으면 나열된 패키지만 설치 스크립트를 실행할 수 있습니다.

예시:

{
  "pnpm": {
    "onlyBuiltDependencies": ["fsevents"]
  }
}

pnpm.allowedDeprecatedVersions​

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

예시:

{
  "pnpm": {
    "allowedDeprecatedVersions": {
      "express": "1",
      "request": "*"
    }
  }
}

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

pnpm.patchedDependencies​

이 필드는 pnpm patch-commit을 실행할 때 자동으로 추가/업데이트됩니다. 키가 패키지 이름과 정확한 버전이어야 하는 딕셔너리입니다. 값은 패치 파일에 대한 상대 경로여야 합니다.

예시:

{
  "pnpm": {
    "patchedDependencies": {
      "express@4.18.1": "patches/express@4.18.1.patch"
    }
  }
}

pnpm.allowNonAppliedPatches​

true인 경우 patchedDependencies 필드의 일부 패치가 적용되지 않은 경우에도 설치가 실패하지 않습니다.

{
  "pnpm": {
    "patchedDependencies": {
      "express@4.18.1": "patches/express@4.18.1.patch"
    }
    "allowNonAppliedPatches": true
}

pnpm.updateConfig​

pnpm.updateConfig.ignoreDependencies​

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

{
  "pnpm": {
    "updateConfig": {
      "ignoreDependencies": ["load-json-file"]
    }
  }
}

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

pnpm.auditConfig​

pnpm.auditConfig.ignoreCves​

pnpm audit 명령에서 무시할 CVE ID 목록입니다.

{
  "pnpm": {
    "auditConfig": {
      "ignoreCves": [
        "CVE-2022-36313"
      ]
    }
  }
}

pnpm.requiredScripts​

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

{
  "pnpm": {
    "requiredScripts": ["build"]
  }
}

resolutions​

pnpm.overrides와 동일합니다. Yarn에서 더 쉽게 마이그레이션하기 위해 활용합니다.