{"id":13912433,"url":"https://github.com/npm/package-json","last_synced_at":"2025-05-15T04:00:27.998Z","repository":{"id":40507286,"uuid":"379075817","full_name":"npm/package-json","owner":"npm","description":"Programmatic API to update package.json","archived":false,"fork":false,"pushed_at":"2025-04-08T22:14:09.000Z","size":365,"stargazers_count":78,"open_issues_count":6,"forks_count":11,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-05-08T00:53:48.729Z","etag":null,"topics":["npm-cli"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/npm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-21T22:13:21.000Z","updated_at":"2025-04-08T09:17:35.000Z","dependencies_parsed_at":"2024-11-21T09:02:22.979Z","dependency_job_id":"96b7189f-f4d8-4d90-a5f5-7a5eefddc92f","html_url":"https://github.com/npm/package-json","commit_stats":{"total_commits":48,"total_committers":5,"mean_commits":9.6,"dds":0.6458333333333333,"last_synced_commit":"9dfd8dacd05d5b2519831cbd4482e1de029299f6"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Fpackage-json","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Fpackage-json/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Fpackage-json/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Fpackage-json/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/npm","download_url":"https://codeload.github.com/npm/package-json/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254227582,"owners_count":22035664,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["npm-cli"],"created_at":"2024-08-07T01:01:27.537Z","updated_at":"2025-05-15T04:00:27.909Z","avatar_url":"https://github.com/npm.png","language":"JavaScript","funding_links":[],"categories":["others"],"sub_categories":[],"readme":"# @npmcli/package-json\n\n[![npm version](https://img.shields.io/npm/v/@npmcli/package-json)](https://www.npmjs.com/package/@npmcli/package-json)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/npm/package-json/ci.yml?branch=main)](https://github.com/npm/package-json)\n\nProgrammatic API to update `package.json` files. Updates and saves files the\nsame way the **npm cli** handles them.\n\n## Install\n\n`npm install @npmcli/package-json`\n\n## Usage:\n\n```js\nconst PackageJson = require('@npmcli/package-json')\nconst pkgJson = await PackageJson.load(path)\n// $ cat package.json\n// {\n//   \"name\": \"foo\",\n//   \"version\": \"1.0.0\",\n//   \"dependencies\": {\n//     \"a\": \"^1.0.0\",\n//     \"abbrev\": \"^1.1.1\"\n//   }\n// }\n\npkgJson.update({\n  dependencies: {\n    a: '^1.0.0',\n    b: '^1.2.3',\n  },\n  workspaces: [\n    './new-workspace',\n  ],\n})\n\nawait pkgJson.save()\n// $ cat package.json\n// {\n//   \"name\": \"foo\",\n//   \"version\": \"1.0.0\",\n//   \"dependencies\": {\n//     \"a\": \"^1.0.0\",\n//     \"b\": \"^1.2.3\"\n//   },\n//   \"workspaces\": [\n//     \"./new-workspace\"\n//   ]\n// }\n```\n\nThere is also a helper function exported for opening a package.json file\nwith no extra normalization or saving functionality.\n\n```js\nconst { readPackage } = require('@npmcli/package-json/lib/read-package')\nconst rawData = await readPackage('./package.json')\n// rawData will now have the package.json contents with no changes or normalizations\n```\n\n## API:\n\n### `constructor()`\n\nCreates a new empty instance of `PackageJson`.\n\n---\n\n### `async PackageJson.create(path)`\n\nCreates an empty `package.json` at the given path. If one already exists\nit will be overwritten.\n\n---\n\n### `async PackageJson.load(path, opts = {})`\n\nLoads a `package.json` at the given path.\n\n- `opts`: `Object` can contain:\n  - `create`: `Boolean` if true, a new package.json will be created if one does not already exist. Will not clobber ane existing package.json that can not be parsed.\n\n### Example:\n\nLoads contents of a `package.json` file located at `./`:\n\n```js\nconst PackageJson = require('@npmcli/package-json')\nconst pkgJson = new PackageJson()\nawait pkgJson.load('./')\n```\n\nThrows an error in case a `package.json` file is missing or has invalid contents.\n\n---\n\n### **static** `async PackageJson.load(path)`\n\nConvenience static method that returns a new instance and loads the contents of a `package.json` file from that location.\n\n- `path`: `String` that points to the folder from where to read the `package.json` from\n\n### Example:\n\nLoads contents of a `package.json` file located at `./`:\n\n```js\nconst PackageJson = require('@npmcli/package-json')\nconst pkgJson = await PackageJson.load('./')\n```\n\n---\n\n### `async PackageJson.normalize()`\n\nIntended for normalizing package.json files in a node_modules tree.  Some light normalization is done to ensure that it is ready for use in `@npmcli/arborist`\n\n- `path`: `String` that points to the folder from where to read the `package.json` from\n- `opts`: `Object` can contain:\n  - `strict`: `Boolean` enables optional strict mode when applying the `normalizeData` step\n  - `steps`: `Array` optional normalization steps that will be applied to the `package.json` file, replacing the default steps\n  - `root`: `Path` optional git root to provide when applying the `gitHead` step\n  - `changes`: `Array` if provided, a message about each change that was made to the packument will be added to this array\n\n---\n\n### **static** `async PackageJson.normalize(path, opts = {})`\n\nConvenience static that calls `load` before calling `normalize`\n\n- `path`: `String` that points to the folder from where to read the `package.json` from\n- `opts`: `Object` can contain:\n  - `strict`: `Boolean` enables optional strict mode when applying the `normalizeData` step\n  - `steps`: `Array` optional normalization steps that will be applied to the `package.json` file, replacing the default steps\n  - `root`: `Path` optional git root to provide when applying the `gitHead` step\n  - `changes`: `Array` if provided, a message about each change that was made to the packument will be added to this array\n\n---\n\n### `async PackageJson.prepare()`\n\nLike `normalize` but intended for preparing package.json files for publish.\n\n---\n\n### **static** `async PackageJson.prepare(path, opts = {})`\n\nConvenience static that calls `load` before calling `prepare`\n\n- `path`: `String` that points to the folder from where to read the `package.json` from\n- `opts`: `Object` can contain:\n  - `strict`: `Boolean` enables optional strict mode when applying the `normalizeData` step\n  - `steps`: `Array` optional normalization steps that will be applied to the `package.json` file, replacing the default steps\n  - `root`: `Path` optional git root to provide when applying the `gitHead` step\n  - `changes`: `Array` if provided, a message about each change that was made to the packument will be added to this array\n\n---\n\n### `async PackageJson.fix()`\n\nLike `normalize` but intended for the `npm pkg fix` command.\n\n---\n\n### `PackageJson.update(content)`\n\nUpdates the contents of a `package.json` with the `content` provided.\n\n- `content`: `Object` containing the properties to be updated/replaced in the\n`package.json` file.\n\nSpecial properties like `dependencies`, `devDependencies`,\n`optionalDependencies`, `peerDependencies` will have special logic to handle\nthe update of these options, such as sorting and deduplication.\n\n### Example:\n\nAdds a new script named `new-script` to your `package.json` `scripts` property:\n\n```js\nconst PackageJson = require('@npmcli/package-json')\nconst pkgJson = await PackageJson.load('./')\npkgJson.update({\n  scripts: {\n    ...pkgJson.content.scripts,\n    'new-script': 'echo \"Bom dia!\"'\n  }\n})\n```\n\n**NOTE:** When working with dependencies, it's important to provide values for\nall known dependency types as the update logic has some interdependence in\nbetween these properties.\n\n### Example:\n\nA safe way to add a `devDependency` AND remove all peer dependencies of an\nexisting `package.json`:\n\n```js\nconst PackageJson = require('@npmcli/package-json')\nconst pkgJson = await PackageJson.load('./')\npkgJson.update({\n  dependencies: pkgJson.content.dependencies,\n  devDependencies: {\n    ...pkgJson.content.devDependencies,\n    foo: '^foo@1.0.0',\n  },\n  peerDependencies: {},\n  optionalDependencies: pkgJson.content.optionalDependencies,\n})\n```\n\n---\n\n### **get** `PackageJson.content`\n\nGetter that retrieves the normalized `Object` read from the loaded\n`package.json` file.\n\n### Example:\n\n```js\nconst PackageJson = require('@npmcli/package-json')\nconst pkgJson = await PackageJson.load('./')\npkgJson.content\n// -\u003e {\n//   name: 'foo',\n//   version: '1.0.0'\n// }\n```\n\n---\n\n### `async PackageJson.save()`\n\nSaves the current `content` to the same location used when calling\n`load()`.\n\n## LICENSE\n\n[ISC](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpm%2Fpackage-json","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnpm%2Fpackage-json","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpm%2Fpackage-json/lists"}