# @financial-times/package-json

> This library allows you to load, manipulate and write the contents of a [`package.json`](https://docs.npmjs.com/files/package.json.html) file. It also provides a [changelog](#getchangelog) detailing any changes that have been made.

Latest version **4.0.0** (published 2023-06-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install @financial-times/package-json
pnpm add @financial-times/package-json
yarn add @financial-times/package-json
bun add @financial-times/package-json
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2023-06-30 |
| First published | 2019-02-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | 16.x \|\| 18.x |
| Dependencies | 0 |
| Unpacked size | 67.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | robertboulton, seraph2000, robgodfrey, hamza.samih, notlee, emmalewis, aendra, the-ft, rowanmanning, chee, alexwilson |
| Keywords | package.json |

## Links

- npm: https://www.npmjs.com/package/@financial-times/package-json
- Repository: https://github.com/financial-times/tooling-helpers
- Homepage: https://github.com/Financial-Times/tooling-helpers/blob/HEAD/packages/package-json/README.md
- Issues: https://github.com/financial-times/tooling-helpers/issues
- npm.io page: https://npm.io/package/@financial-times/package-json

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 4.0.0 (latest) — 2023-06-30
- 3.0.0 — 2020-10-02
- 2.0.1 — 2019-10-16
- 2.0.0 — 2019-04-26
- 1.0.2 — 2019-02-22
- 1.0.1 — 2019-02-20

## README

# package-json

This library allows you to load, manipulate and write the contents of
a [`package.json`](https://docs.npmjs.com/files/package.json.html) file.
It also provides a [changelog](#getchangelog) detailing any changes
that have been made.

# Usage

```
npm install @financial-times/package-json
```

## loadPackageJson

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.

```javascript
const loadPackageJson = require("@financial-times/package-json");
const packageJson = loadPackageJson({ filepath: `filepath/to/package.json` });
```

Methods returned:

- [get](#get)
- [hasChangesToWrite](#haschangestowrite)
- [writeChanges](#writechanges)
- [getField](#getfield)
- [setField](#setfield)
- [removeField](#removefield)
- [requireDependency](#requiredependency)
- [removeDependency](#removedependency)
- [requireScript](#requirescript)
- [removeScript](#removescript)
- [getChangelog](#getchangelog)

### get

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.

```javascript
packageJson.get();
```

### hasChangesToWrite

Checks if there are file changes to write.

```javascript
packageJson.hasChangesToWrite(); // true or false
```

### writeChanges

Writes to the `package.json` file.

```javascript
packageJson.writeChanges(); // true
```

### getField

Gets a specific field from the `package.json` object, by passing the field as an argument.

```javascript
packageJson.getField("name"); // "@financial-times/package-json"
```

### setField

Sets the value for a specific field in the `package.json` object and returns a changelog entry.

```javascript
packageJson.setField("name", "newName");
```

Returns a changelog entry object:

```json
{
  "event": "setField",
  "field": "name",
  "meta": {},
  "previousValue": "oldName",
  "alreadyExisted": false
}
```

### removeField

Removes a specific field in the `package.json` object and returns a changelog entry.

```javascript
packageJson.removeField("license");
```

Returns a changelog entry object:

```json
{
  "event": "removeField",
  "field": "license",
  "meta": {},
  "previousValue": "MIT",
  "alreadyExisted": true
}
```

### requireDependency

Requires a package to exist as a dependency in `package.json`.

```javascript
packageJson.requireDependency({
  pkg: "prettier",
  version: "1.16.4",
  field: "devDependencies"
});
```

Returns a changelog entry object:

```json
{
  "event": "requireDependency",
  "field": "devDependencies",
  "meta": {
    "pkg": "prettier",
    "version": "1.16.4"
  },
  "previousValue": "1.16.3",
  "alreadyExisted": true
}
```

### removeDependency

Removes a package as a dependency from `package.json`.

```javascript
packageJson.removeDependency({
  pkg: "prettier",
  version: "1.16.4",
  field: "devDependencies"
});
```

Returns a changelog entry object, or `false` if the dependency doesn't exist:

```json
{
  "event": "removeDependency",
  "field": "devDependencies",
  "meta": {
    "pkg": "prettier"
  },
  "previousValue": "1.16.3",
  "alreadyExisted": true
}
```

### requireScript

Requires a script to exist in the `scripts` field of `package.json`.

```javascript
packageJson.requireScript({
  stage: "test",
  command: "npm run unit-test"
});
```

Returns a changelog entry object:

```json
{
  "event": "requireScript",
  "field": "scripts",
  "meta": {
    "stage": "test"
  },
  "alreadyExisted": true
}
```

### removeScript

Requires a script to exist in the `scripts` field of `package.json`.

```javascript
packageJson.removeScript({
  stage: "lint"
});
```

Returns a changelog entry object:

```json
{
  "event": "removeScript",
  "field": "scripts",
  "meta": {
    "stage": "lint"
  },
  "alreadyExisted": true
}
```

### getChangelog

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` or `requireScript`
- `field` - The field in `package.json` that was changed
- `alreadyExisted` - Flag whether the field already existed
- `previousValue` - Previous value of the field
- `meta` - 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**

```javascript
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)"
```

---
_Source: https://npm.io/package/@financial-times/package-json · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._