@nossbigg/peerdeps-manager

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

Usage no npm install needed!

<script type="module">
  import nossbiggPeerdepsManager from 'https://cdn.skypack.dev/@nossbigg/peerdeps-manager';
</script>

README

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).

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:

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