@npmcli/package-json

What is @npmcli/package-json?

@npmcli/package-json is a Node.js library that provides utilities for reading, manipulating, and writing package.json files. It simplifies the process of handling package.json files programmatically, making it easier to manage dependencies, scripts, and other metadata in a Node.js project.

What are @npmcli/package-json's main functionalities?

Read package.json

This feature allows you to read the contents of a package.json file. The code sample demonstrates how to load the package.json file from the current working directory and log its contents.

const { PackageJson } = require('@npmcli/package-json');

async function readPackageJson() {
  const pkg = await PackageJson.load(process.cwd());
  console.log(pkg.content);
}

readPackageJson();

Update package.json

This feature allows you to update the contents of a package.json file. The code sample demonstrates how to change the version of the package and save the updated package.json file.

const { PackageJson } = require('@npmcli/package-json');

async function updatePackageJson() {
  const pkg = await PackageJson.load(process.cwd());
  pkg.update({ version: '1.0.1' });
  await pkg.save();
}

updatePackageJson();

Add dependency

This feature allows you to add a new dependency to the package.json file. The code sample demonstrates how to add a new package to the dependencies section and save the updated package.json file.

const { PackageJson } = require('@npmcli/package-json');

async function addDependency() {
  const pkg = await PackageJson.load(process.cwd());
  pkg.update({ dependencies: { 'new-package': '^1.0.0' } });
  await pkg.save();
}

addDependency();

Other packages similar to @npmcli/package-json

edit-json-file

edit-json-file is a simple Node.js library for editing JSON files. It provides basic functionalities for reading, updating, and saving JSON files. Compared to @npmcli/package-json, it is more generic and not specifically tailored for package.json files.

jsonfile

jsonfile is a Node.js library for easily reading and writing JSON files. It offers a straightforward API for working with JSON files but lacks the specialized features for handling package.json files that @npmcli/package-json provides.

write-json-file

write-json-file is a Node.js library focused on writing JSON files. It provides a simple API for writing JSON data to a file. While it is useful for general JSON file operations, it does not offer the package.json-specific utilities found in @npmcli/package-json.

README

@npmcli/package-json

Programmatic API to update package.json files. Updates and saves files the same way the npm cli handles them.

Install

npm install @npmcli/package-json

Usage:

const PackageJson = require('@npmcli/package-json')
const pkgJson = await PackageJson.load(path)
// $ cat package.json
// {
//   "name": "foo",
//   "version": "1.0.0",
//   "dependencies": {
//     "a": "^1.0.0",
//     "abbrev": "^1.1.1"
//   }
// }

pkgJson.update({
  dependencies: {
    a: '^1.0.0',
    b: '^1.2.3',
  },
  workspaces: [
    './new-workspace',
  ],
})

await pkgJson.save()
// $ cat package.json
// {
//   "name": "foo",
//   "version": "1.0.0",
//   "dependencies": {
//     "a": "^1.0.0",
//     "b": "^1.2.3"
//   },
//   "workspaces": [
//     "./new-workspace"
//   ]
// }

There is also a helper function exported for opening a package.json file with no extra normalization or saving functionality.

const { readPackage } = require('@npmcli/package-json/lib/read-package')
const rawData = await readPackage('./package.json')
// rawData will now have the package.json contents with no changes or normalizations

API:

constructor()

Creates a new empty instance of PackageJson.

---

async PackageJson.create(path)

Creates an empty package.json at the given path. If one already exists it will be overwritten.

---

async PackageJson.load(path, opts = {})

Loads a package.json at the given path.

• opts: Object can contain:
  • 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.

Example:

Loads contents of a package.json file located at ./:

const PackageJson = require('@npmcli/package-json')
const pkgJson = new PackageJson()
await pkgJson.load('./')

Throws an error in case a package.json file is missing or has invalid contents.

---

static async PackageJson.load(path)

Convenience static method that returns a new instance and loads the contents of a package.json file from that location.

• path: String that points to the folder from where to read the package.json from

Example:

Loads contents of a package.json file located at ./:

const PackageJson = require('@npmcli/package-json')
const pkgJson = await PackageJson.load('./')

---

async PackageJson.normalize()

Intended 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

• path: String that points to the folder from where to read the package.json from
• opts: Object can contain:
  • strict: Boolean enables optional strict mode when applying the normalizeData step
  • steps: Array optional normalization steps that will be applied to the package.json file, replacing the default steps
  • root: Path optional git root to provide when applying the gitHead step
  • changes: Array if provided, a message about each change that was made to the packument will be added to this array

---

static async PackageJson.normalize(path, opts = {})

Convenience static that calls load before calling normalize

• path: String that points to the folder from where to read the package.json from
• opts: Object can contain:
  • strict: Boolean enables optional strict mode when applying the normalizeData step
  • steps: Array optional normalization steps that will be applied to the package.json file, replacing the default steps
  • root: Path optional git root to provide when applying the gitHead step
  • changes: Array if provided, a message about each change that was made to the packument will be added to this array

---

async PackageJson.prepare()

Like normalize but intended for preparing package.json files for publish.

---

static async PackageJson.prepare(path, opts = {})

Convenience static that calls load before calling prepare

• path: String that points to the folder from where to read the package.json from
• opts: Object can contain:
  • strict: Boolean enables optional strict mode when applying the normalizeData step
  • steps: Array optional normalization steps that will be applied to the package.json file, replacing the default steps
  • root: Path optional git root to provide when applying the gitHead step
  • changes: Array if provided, a message about each change that was made to the packument will be added to this array

---

async PackageJson.fix()

Like normalize but intended for the npm pkg fix command.

---

PackageJson.update(content)

Updates the contents of a package.json with the content provided.

• content: Object containing the properties to be updated/replaced in the package.json file.

Special properties like dependencies, devDependencies, optionalDependencies, peerDependencies will have special logic to handle the update of these options, such as sorting and deduplication.

Example:

Adds a new script named new-script to your package.json scripts property:

const PackageJson = require('@npmcli/package-json')
const pkgJson = await PackageJson.load('./')
pkgJson.update({
  scripts: {
    ...pkgJson.content.scripts,
    'new-script': 'echo "Bom dia!"'
  }
})

NOTE: When working with dependencies, it's important to provide values for all known dependency types as the update logic has some interdependence in between these properties.

Example:

A safe way to add a devDependency AND remove all peer dependencies of an existing package.json:

const PackageJson = require('@npmcli/package-json')
const pkgJson = await PackageJson.load('./')
pkgJson.update({
  dependencies: pkgJson.content.dependencies,
  devDependencies: {
    ...pkgJson.content.devDependencies,
    foo: '^foo@1.0.0',
  },
  peerDependencies: {},
  optionalDependencies: pkgJson.content.optionalDependencies,
})

---

get PackageJson.content

Getter that retrieves the normalized Object read from the loaded package.json file.

Example:

const PackageJson = require('@npmcli/package-json')
const pkgJson = await PackageJson.load('./')
pkgJson.content
// -> {
//   name: 'foo',
//   version: '1.0.0'
// }

---

async PackageJson.save()

Saves the current content to the same location used when calling load().

LICENSE

ISC

Changelog

6.0.0 (2024-09-26)

⚠️ BREAKING CHANGES

• @npmcli/package-json now supports node ^18.17.0 || >=20.5.0

Bug Fixes

• 8196f27 #126 align to npm 10 node engine range (@reggi)

Dependencies

• 5bdf533 #126 proc-log@5.0.0
• 136ba6e #126 normalize-package-data@7.0.0
• 12318c0 #126 json-parse-even-better-errors@4.0.0
• 324d7ba #126 hosted-git-info@8.0.0

Chores

• 855676d #117 bump @npmcli/eslint-config from 4.0.5 to 5.0.0 (#117) (@dependabot[bot])
• c421ce9 #125 bump read-package-json-fast from 3.0.2 to 4.0.0 (#125) (@dependabot[bot])
• 1f182e6 #126 run template-oss-apply (@reggi)