Noiseless Praying Mantis

    @npmcli/package-json
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/npmcli__package-json package

    2.0.0 • Public • Published

    @npmcli/package-json

    npm version Build Status

    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"
    //   ]
    // }

    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('./')

    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
    // -> {
    //   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 by npm@6 and in npm@7 for publishing.

    LICENSE

    ISC

    Keywords

    Install

    npm i @npmcli/package-json

    DownloadsWeekly Downloads

    1,258,225

    Version

    2.0.0

    License

    ISC

    Unpacked Size

    12.4 kB

    Total Files

    7

    Last publish

    Collaborators

    • fritzy
    • darcyclarke
    • nlf
    • gar
    • lukekarrys