Fixpack: package.json Scrubber

4.0.0 · active · verified Wed Apr 22

fixpack is a command-line interface (CLI) tool designed to enforce a consistent structure and content within `package.json` files. It automates the reordering of top-level keys, alphabetically sorts `dependencies` and `devDependencies`, and ensures a newline at the end of the file. The tool also provides configurable warnings for missing recommended fields (e.g., `description`, `author`, `license`) and errors for missing required fields (e.g., `name`, `version`). A key differentiator is its ability to tolerate malformed JSON using the `alce` library, making it robust against minor syntax errors. The current stable version is 4.0.0, though the project's update cadence appears irregular, with previous major updates and patch fixes spanning several years. It supports extensive configuration via `.fixpackrc` files and CLI arguments, and can be integrated into CI/CD pipelines using its `--dryRun` flag to check for compliance without modifying files.

Common errors

```
Error: package.json not found in current directory or any parent directories.
```
cause The `fixpack` command was executed in a directory that does not contain a `package.json` file, and no `package.json` was found in any parent directories up to the root.

fix Ensure you are running `fixpack` from the root directory of your project, or a subdirectory where a `package.json` can be found in a parent directory.
```
fixpack: command not found
```
cause The `fixpack` executable is not in your system's PATH, typically because it was not installed globally or the global `node_modules/.bin` directory is not in your PATH.

fix Install `fixpack` globally using `npm i -g fixpack` or `yarn global add fixpack`. If it's already installed globally, check your shell's PATH configuration to ensure the npm global bin directory is included.
```
fixpack exited with code 1
```
cause This exit code indicates that `fixpack` either made changes to `package.json` or, if `--dryRun` was used, detected that changes were necessary to bring the file into compliance. This is part of its intended behavior for CI checks.

fix If running interactively, this means your `package.json` was fixed. If in CI and `--dryRun` was used, it means the `package.json` was not compliant. Review the output for warnings/errors and ensure your `package.json` meets the configured requirements. Run `fixpack` without `--dryRun` to apply changes.

Warnings

breaking Version 2.0.0 introduced configuration via a `.fixpackrc` file or CLI arguments, replacing previous configuration methods. Users upgrading from earlier versions may need to create a `.fixpackrc` file or adjust their command-line usage.
Fix: Create a `.fixpackrc` file in your project root or home directory, or pass configuration options directly as CLI arguments (e.g., `fixpack --indent 2`).
gotcha By default, `fixpack` modifies your `package.json` file in place without creating a backup. This can be destructive if not used carefully.
Fix: Always commit your `package.json` to version control before running `fixpack`, or use the `--dryRun` flag first to preview changes. For critical environments, consider piping the output of `fixpack` to a temporary file before overwriting.
gotcha The `required` configuration option (defaulting to `name` and `version`) will cause `fixpack` to exit with an error (non-zero exit code) if any of these fields are missing. This is intentional for CI, but can unexpectedly halt processes.
Fix: Ensure all fields listed in your `required` configuration are present in `package.json`. Adjust the `required` array in your `.fixpackrc` if certain fields are not strictly necessary for your project.
gotcha The `fixpack` command exits with code `1` if changes were made to `package.json` (or if changes *would* be made when using `--dryRun`), and `0` if the file was already correctly formatted. This behavior is designed for CI checks but can be misinterpreted as an error.
Fix: When integrating into CI, explicitly check for exit code `0` for success if the goal is to ensure an already fixed `package.json`. If using `--dryRun` as a check, an exit code of `1` indicates a non-compliant file.
gotcha The `wipe` option will destructively set all dependency versions in `dependencies` and `devDependencies` to `*`. This is intended for specific workflows (e.g., bulk updates) and should be used with extreme caution as it removes explicit version ranges.
Fix: Only use `fixpack --wipe` if you understand its implications and intend to immediately follow up with `npm update --save && npm update --save-dev` or similar commands to reinstall specific version ranges. Avoid using it generally.

Install

npm install fixpack npm
yarn add fixpack yarn
pnpm add fixpack pnpm

Imports

fixpack CLI
```
npm i -g fixpack
fixpack
```
fixpack is primarily a command-line interface (CLI) tool and is not typically used via programmatic imports in JavaScript/TypeScript code. Its functionality is accessed by executing the `fixpack` command in the terminal.

Quickstart

Demonstrates global installation and execution of fixpack, including its use in a post-install hook and a dry run for CI checks.

npm i -g fixpack

# Navigate to your project directory
cd my-project

# Run fixpack to clean up package.json
fixpack

# Example of using fixpack after installing a new package
npm i cool_package --save && fixpack

# Check if package.json needs fixing without modifying it (for CI/CD)
# This will exit with code 1 if changes are needed, 0 if already fixed.
fixpack --dryRun

view raw JSON →