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"
// }
// }
API:
constructor(path)
Creates a new instance of PackageJson
.
path
:String
that points to the folder from where to read thepackage.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.
async PackageJson.load(path)
static 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 thepackage.json
from
Example:
Loads contents of the package.json
file located at ./
:
const PackageJson = require('@npmcli/package-json')
const pkgJson = await PackageJson.load('./')
PackageJson.update(content)
Updates the contents of the package.json
with the content
provided.
content
:Object
containing the properties to be updated/replaced in thepackage.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,
})
PackageJson.content
get 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 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 bynpm@6
and innpm@7
for publishing.