@nossbigg/peerdeps-manager

peerdeps-manager

A simple CLI utility to install (and uninstall) your node peer dependencies to your dev dependencies.

Why does this exist?

Because npm (v4-6) and yarn does not support installing peer depedencies (as of Sep 2021).

• Related npm issue, Related yarn issue

Note: This tool is inspired by install-peerdeps and does roughly the same thing, but with a declarative approach.

Usage

• Install peerdeps-manager: yarn add @nossbigg/peerdeps-manager -D or npm install @nossbigg/peerdeps-manager -D

• Add .peerdeps-manager.config.js to define tool config

• Install dependencies defined in config: peerdeps-manager set

• Uninstall dependencies defined in config: peerdeps-manager unset

• Options to invoke peerdeps-manager:

  • Invoke via sequential command:

    peerdeps-manager set && jest
    
    // or
    
    peerdeps-manager unset && create-react-app start

  • Invoke via pre/post command hooks:

    // package.json
    {
      "scripts": {
        "pretest": "peerdeps-manager set",
        "test": "jest"
      }
    }

.peerdeps-manager.config.js config file

peerdeps-manager requires a .peerdeps-manager.config.js config file from the root of the project for configuring the tool

Config file schema:

// .peerdeps-manager.config.js
const config = {
  // where you define your packages to install/uninstall during set/unset actions
  // format: same as per provided to npm install/uninstall or yarn add/remove to maximize compatibility
  set: { packages: ["lodash.uniq", "lodash.template@4.0.6"] },
  unset: {
    packages: ["lodash.uniq", "lodash.template"],
    // automatically restores package.json to last git checked-in state, requires 'git' in CLI
    // set to 'false' to disable this feature
    doGitRestorePackageJson: true,
  },
};

module.exports = config;

Note on unset.doGitRestorePackageJson:

• npm uninstall/yarn remove will remove a given package from all dependencies fields, including peerDependencies
• However, after an unset, a library package author would like to preserve peerDependencies, in order to indicate what peer dependencies a given library must have in order to work correctly
• Thus, for an ideal developer experience, during the unset step, peerdeps-manager will do a git checkout package.json by default in order to restore the peerDependencies that were lost due to uninstalling the temporary packages.
• You can disable this feature by setting doGitRestorePackageJson: false (eg. if you are experimenting with your package.json and you do not want to lose your changes)

Related documentation:

• npm install, npm uninstall
• yarn add, yarn remove

Supported package managers:

• npm
• yarn

Use case

As a react component library maintainer, I would like to:

1. Specify react and react-dom in my peerDependencies
2. Uninstall react and react-dom in my devDependencies before running a webpack dev instance locally
   • to ensure that my React component is working as expected.
3. Install react and react-dom in my devDependencies before running my tests so that my test suite has the right dependencies to function and pass
   • eg. enzyme and react-testing-library requires the aforementioned dependencies to work correctly
4. Uninstall react and react-dom before publishing my package for it to work correctly

Developing

1. Clone the repo
2. Install its dependencies: npm i or yarn
3. Make peerdeps-manager available to be locally symlinked:
   • (in ./peerdeps-manager) npm link
4. Use peerdeps-manager in a project:
   • (in other project directory) npm install -D @nossbigg/peerdeps-manager
   • (in other project directory) npm link @nossbigg/peerdeps-manager
5. Publish package: npm publish --access public