This library allows you to load, manipulate and write the contents of
a package.json
file.
It also provides a changelog detailing any changes
that have been made.
npm install @financial-times/package-json
After loading the specified package.json
file into memory, the loadPackageJson
method returns a collection of methods that can be used for changing the package.json
document and writing those changes back to disk.
const loadPackageJson = require("@financial-times/package-json");
const packageJson = loadPackageJson({ filepath: `filepath/to/package.json` });
Methods returned:
- get
- hasChangesToWrite
- writeChanges
- getField
- setField
- removeField
- requireDependency
- removeDependency
- requireScript
- removeScript
- getChangelog
Returns an object representing the current working state of the package.json
document. This may be different to what exists on the file system if changes have not yet been written by calling the writeChanges
method.
packageJson.get();
Checks if there are file changes to write.
packageJson.hasChangesToWrite(); // true or false
Writes to the package.json
file.
packageJson.writeChanges(); // true
Gets a specific field from the package.json
object, by passing the field as an argument.
packageJson.getField("name"); // "@financial-times/package-json"
Sets the value for a specific field in the package.json
object and returns a changelog entry.
packageJson.setField("name", "newName");
Returns a changelog entry object:
{
"event": "setField",
"field": "name",
"meta": {},
"previousValue": "oldName",
"alreadyExisted": false
}
Removes a specific field in the package.json
object and returns a changelog entry.
packageJson.removeField("license");
Returns a changelog entry object:
{
"event": "removeField",
"field": "license",
"meta": {},
"previousValue": "MIT",
"alreadyExisted": true
}
Requires a package to exist as a dependency in package.json
.
packageJson.requireDependency({
pkg: "prettier",
version: "1.16.4",
field: "devDependencies"
});
Returns a changelog entry object:
{
"event": "requireDependency",
"field": "devDependencies",
"meta": {
"pkg": "prettier",
"version": "1.16.4"
},
"previousValue": "1.16.3",
"alreadyExisted": true
}
Removes a package as a dependency from package.json
.
packageJson.removeDependency({
pkg: "prettier",
version: "1.16.4",
field: "devDependencies"
});
Returns a changelog entry object, or false
if the dependency doesn't exist:
{
"event": "removeDependency",
"field": "devDependencies",
"meta": {
"pkg": "prettier"
},
"previousValue": "1.16.3",
"alreadyExisted": true
}
Requires a script to exist in the scripts
field of package.json
.
packageJson.requireScript({
stage: "test",
command: "npm run unit-test"
});
Returns a changelog entry object:
{
"event": "requireScript",
"field": "scripts",
"meta": {
"stage": "test"
},
"alreadyExisted": true
}
Requires a script to exist in the scripts
field of package.json
.
packageJson.removeScript({
stage: "lint"
});
Returns a changelog entry object:
{
"event": "removeScript",
"field": "scripts",
"meta": {
"stage": "lint"
},
"alreadyExisted": true
}
The changelog represents all the changes that have been made to the package.json
object, regardless of whether they have yet been written to the file.
The changelog is made up of entry objects, which all have the following properties:
event
- The type of event i.e.setField
,requireDependency
,removeDependency
orrequireScript
field
- The field inpackage.json
that was changedalreadyExisted
- Flag whether the field already existedpreviousValue
- Previous value of the fieldmeta
- An object containing extra details about the change e.g.pkg
,version
,stage
You can access the changelog entries with the following methods:
getChangelog()
getChangelog.asMessages()
getChangelog.lastEntry()
getChangelog.lastEntryAsMessage()
Examples of working with the changelog
packageJson.requireDependency({
pkg: "prettier",
version: "1.16.4",
field: "devDependencies"
});
packageJson.requireScript({
stage: "test",
command: "npm run unit-test"
});
const changelogObjects = packageJson.getChangelog();
/*
[
{
event: "requireDependency",
field: "devDependencies",
meta: {
pkg: "prettier",
version: "1.16.4"
},
previousValue: "1.16.3",
alreadyExisted: true
},
{
event: "requireScript",
field: "scripts",
meta: {
stage: "test"
},
alreadyExisted: true
}
]
*/
const changelogMessages = packageJson.getChangelog.asMessages();
/*
[
"Required package prettier@1.16.4 in devDependencies, previously 1.16.3",
"Required script for stage 'test' (overwrote existing command)"
]
*/
const lastChangelogEntryObject = packageJson.getChangelog.lastEntry();
/*
{
event: "requireScript",
field: "scripts",
meta: {
stage: "test"
},
alreadyExisted: true
}
*/
const lastChangelogEntryMessage = packageJson.getChangelog.lastEntryAsMessage();
// "Required script for stage 'test' (overwrote existing command)"