better-deps

CLI for reducing issues with JavaScript dependencies in monorepos.

⚠️ Since this tool was written, the capabilities of package managers and syncpack have improved, rendering this tool largely redundant. The hoist-dev-deps and unpin-dev-deps rules may still be useful for one-time migration purposes if they match your preferences.

Caveat

The changes implemented by this CLI may help reduce issues encountered in certain common monorepo setups, but they may not be applicable or preferable in all cases (especially hoist-dev-deps).

Commands

Currently, each command has a --check mode which can be used in CI, but the commands must be run individually. In the future, the tool may be modified to follow more of a "linter" model with a configurable list of rules, or entirely rewritten as an ESLint plugin.

• hoist-dev-deps (consider catalog: versions instead)
• ~~star-local-dev-deps~~ (use workspace: ranges and/or syncpack instead)
• unpin-dev-deps (consider using syncpack instead)

hoist-dev-deps

Remove devDependencies from individual packages and declare them at the monorepo root instead.

This approach helps mitigate issues with package manager behavior (particularly Yarn v1) and reduce churn, but it has some downsides. Alternatively, some repos may prefer to use a package manager which implements strict installation layout (essentially the opposite of this strategy).

RECOMMENDED: If your main concerns are version consistency and reducing churn, consider catalog: versions if using yarn 4 or pnpm. syncpack (with default settings) can also enforce version consistency.

Options

• --check: Check for issues without making any changes, and exit non-zero if issues are found (good for CI)
• --exclude <deps...>: Don't hoist these devDependencies
• --only <deps...>: Only hoist these devDependencies (mutually exclusive with other options)
• --threshold <percent>: Only hoist devDependencies used in >= this percent of packages. This can help mitigate concerns about how hoisting makes it less explicit which packages actually use which dependencies.
  • --always <deps...>: Always hoist these devDependencies (only relevant with --threshold)

Usage

# Hoist all dev deps
better-deps hoist-dev-deps

# Check that no new non-hoisted deps have been introduced
better-deps hoist-dev-deps --check

# Hoist all dev deps except @storybook/html
better-deps hoist-dev-deps --exclude @storybook/html

# Hoist dev deps used by >= 50% of packages
better-deps hoist-dev-deps --threshold 50

# As above, but always hoist typescript and react deps
better-deps hoist-dev-deps --threshold 50 --always typescript react react-dom @types/react @types/react-dom

# Only hoist @types/react and @types/react-dom
better-deps hoist-dev-deps --only @types/react @types/react-dom

Why

This is a potentially "less bad" approach to mitigate issues with package manager behavior and reduce churn, though it has some downsides.

• Pros:
  • Reduces churn and merge conflicts when updating devDependencies. (better managed with catalog: versions if supported)
    • This is especially important for frequent updates with a tool such as Renovate or Dependabot, though potentially less so with Renovate now that its recommended config presets no longer pin devDependencies by default.
  • Makes it easier for a human to update devDependencies without accidentally introducing mismatches and duplicates. (better managed with syncpack or catalog: versions)
  • Prevents the wrong version of a dep from being hoisted implicitly. Most package managers don't install dependencies strictly nested within their trees; instead, they flatten the tree to some degree, which involves implicitly hoisting some deps to be installed under the monorepo's root node_modules. Yarn (at least v1) seems nondeterministic about which package version it chooses to install at the repo root if more than one version is present anywhere in the tree, sometimes leading to different behavior between computers. (npm may also have a variant of this problem when generating or updating the lock file.)
• Cons:
  • Makes it less obvious which packages use which devDependencies. This can be mitigated somewhat by using the --threshold option to hoist only things that are widely used.
  • May make it easier for packages to add implicit dependencies in production code. This can be mitigated by lint rules (which is a good practice regardless).

Another approach which eliminates implicit hoisting while avoiding the cons listed above is to use a package manager which implements strict installation layout instead (essentially the opposite of this strategy). Some examples are pnpm, or yarn 4 with nodeLinker: pnpm. Both those managers also support catalogs to prevent package.json churn.

star-local-dev-deps

Change version specs of devDependencies on local packages (those defined within the monorepo) to *.

RECOMMENDED: prefer workspace: ranges for internal dependencies with package managers that support it, and/or use syncpack instead.

Options

• --check: Check for issues without making any changes, and exit non-zero if issues are found (good for CI)

Usage

better-deps star-local-dev-deps

Why

Many monorepos define build scripts or configuration in local packages (which may also be published), and all the other packages have devDependencies on the shared build packages. Using * for those devDependencies minimizes churn and merge conflicts when package versions are updated, while also maintaining the dependency graph.

unpin-dev-deps

Change exact versions of external devDependencies to use ^ or ~ ranges (excluding anything using a prerelease version). This is mainly an easy way to revert Renovate's old behavior of pinning devDependencies.

RECOMMENDED: use syncpack instead, unless you just want one-time migration.

Options

• --check: Check for issues without making any changes, and exit non-zero if issues are found (good for CI)
• --exclude <deps...>: Don't modify these devDependencies
• --patch <deps...>: Only allow patch version of these deps to vary (~)

Usage

# Unpin all dev deps
better-deps unpin-dev-deps

# Unpin all dev deps except typescript and prettier
better-deps unpin-dev-deps --exclude typescript prettier

# Unpin all dev deps, using ~ versions for typescript and prettier
better-deps unpin-dev-deps --patch typescript prettier