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.
@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)
pkgJson.update({
dependencies: {
a: '^1.0.0',
b: '^1.2.3',
},
workspaces: [
'./new-workspace',
],
})
await pkgJson.save()
API:
constructor(path)
Creates a new instance of PackageJson
.
path
: String
that points to the folder from where to read the
package.json
from
async PackageJson.load()
Loads the package.json
at location determined in the path
option of
the constructor.
Example:
Loads contents of the package.json
file located at ./
:
const PackageJson = require('@npmcli/package-json')
const pkgJson = new PackageJson('./')
await pkgJson.load()
Throws an error in case the 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
the 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 the package.json
file located at ./
:
const PackageJson = require('@npmcli/package-json')
const pkgJson = await PackageJson.load('./')
async PackageJson.normalize()
Like load
but intended for reading package.json files in a
node_modules tree. Some light normalization is done to ensure that it
is ready for use in @npmcli/arborist
static async PackageJson.normalize(path)
Convenience static method like load
but for calling normalize
async PackageJson.prepare()
Like load
but intended for reading package.json files before publish.
static async PackageJson.prepare(path)
Convenience static method like load
but for calling prepare
PackageJson.update(content)
Updates the contents of the 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 deduplications.
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
async PackageJson.save()
Saves the current content
to the same location used when initializing
this instance.
Related
When you make a living out of reading and writing package.json
files, you end
up with quite the amount of packages dedicated to it, the npm cli also
uses:
- read-package-json-fast reads
and normalizes
package.json
files the way the npm cli expects it. - read-package-json reads and
normalizes more info from your
package.json
file. Used by npm@6
and in
npm@7
for publishing.
LICENSE
ISC