clean-package

Clean Package

This clean-package tool is used for removing development configuration from 'package.json' before publishing the package to NPM.

Install

npm install clean-package --save-dev

Integrated Usage

The clean-package tool works directly on the 'package.json' file, to avoid breaking the NPM lifecycle. This allows you to add a script to the 'package.json' to clean the file during packing.

{
  "name": "my-package",
  "version": "1.0.0",
  "scripts": {
    "prepack": "clean-package",
    "postpack": "clean-package restore"
  }
}

When the "prepack" script executes, a backup of the original package.json will be created. Ensure this file doesn't make it into your release package.

One way to accomplish this is to add the following to your .npmignore file:

*.backup

See CLI Usage for independent usage instructions.

JSON Configuration Files

Options can be configured in clean-package.config.json at the root of your project (where the package.json is).

{
  "indent": 2,
  "remove": [
    "eslintConfig",
    "jest"
  ]
}

Alternatively, you can choose to specify your configuration from within package.json using the clean-package key like so:

{
  "name": "my-package",
  "version": "1.0.0",
  "clean-package": {
    "indent": 2,
    "remove": [
      "eslintConfig",
      "jest"
    ]
  },

  // Or, a file path to a configuration.
  "clean-package": "./build/clean-package.config.js"
}

JavaScript Configuration File

You can also create the configuration using JavaScript in the clean-package.config.?(c|m)js at the root of your project:

module.exports = {
  indent: '\t',
  replace: {
    'config.port': '8080'
  }
};

Options

backupPath

Type: String
Default: './package.json.backup'

Specifies the location and filename to which the package.json will be backed up.

indent

Type: String | Number
Default: 2

Defines the indentation that's used to format the cleaned package.json. See the space parameter of JSON.stringify for more information.

remove

Type: String[] | (keys: String[]) => String[]

Specifies the keys to be removed from the cleaned package.json; otherwise, null when nothing is to be removed.

Deeper keys can be accessed using a dot (e.g., 'key.keyInsideKey'). Likewise, arrays are accessible using brackets (e.g., 'key.arrKey[0]').

To remove keys that contain a dot, the dot must be escaped. For example, 'exports.\\.' will target "exports": { "." }

replace

Type: Object | (pairs: Object) => Object

Specifies the keys to be replaced in the cleaned package.json; otherwise, null when nothing is to be replaced.

Deeper keys and arrays are accessible in the same manner and allow dot escaping. Additionally, the replaced keys may receive any valid JSON value, including objects.

extends

Type: String | String[]

Specifies the name/s of a shareable configuration.

This package shares a configuration with common settings that can be extended from clean-package/common.

onClean

Type: (hasChanged: boolean, config: CompiledConfig) => void

Notified after the package.json has been cleaned, supplied with an indication as to whether there were changes and the compiled configuration.

onRestore

Type: (hasChanged: boolean, config: CompiledConfig) => void

Notified after the package.json has been restored, supplied with an indication as to whether there were changes and the compiled configuration.

Command Line Usage

clean-package [[<source-path>] <backup-path>] [<option>...]

where <option> is one of:

  -c,  --config <path>                  Specify the path to a configuration file.

  -e,  --extends <name>...              Specify the name to a shareable configuration. (e.g. 'clean-package/common')

  -i,  --indent <value>                 Specify the indentation, overriding configuration from file.

  -rm, --remove <key>...                Specify the keys to remove, overriding configuration from file.

       --remove-add <key>...            Same as --remove without overriding configuration from file.

  -r,  --replace <key>=<value>...       Specify the keys to replace, overriding configuration from file.

       --replace-add <key>=<value>...   Same as --replace without overriding configuration from file.

       --print-config                   Print the combined configuration without executing command.

  -v,  --version                        Print the version number

clean-package restore [[<source-path>] <backup-path>] [<option>...]

alias: r

where <option> is one of:

  -c,  --config <path>                  Specify the path to a configuration file.

  -e,  --extends <name>...              Specify the name to a shareable configuration. (e.g. 'clean-package/common')

       --print-config                   Print the combined configuration without executing command.

Usage in Code

Should you desire, it is also possible to interface this package through code. Simply import the package like any other.

import { load, clean, restore, version } from 'clean-package';

Troubleshooting

How do I remove package scripts and use clean-package restore?

If you're integrating clean-package into the NPM lifecycle, removing all the package.json scripts with clean-package will also remove them from the current execution. This is just how NPM works.

For example, this configuration will remove the postpack script before it is ever requested by npm pack or npm publish, thereby effectively removing the event from the executing lifecycle.

{
  "scripts": {
    "prepack": "clean-package",
    "postpack": "clean-package restore"
  },
  "clean-package": {
    "remove": [
      "clean-package",
      "scripts"
    ]
  }
}

There are multiple ways to work around this (more than are offered here). One solution might be to manually run the command with npx clean-package restore. Another might be to define a custom script that would call pack and clean-package in sequence:

{
  "scripts": {
    "prepack": "clean-package",
    "new:pack": "npm pack && clean-package restore",
    "new:publish": "npm publish && clean-package restore"
  }
}