yarn-why
Explain why a package is installed
TLDR
Show why a Yarn package is installed
SYNOPSIS
yarn why package_name [--json]
PARAMETERS
package_name
The name of the package whose installation reason you want to investigate. This can be any package found within your project's dependency tree.
--json
Outputs the result in a machine-readable JSON format. This option is particularly useful for scripting and integrating yarn-why into automated workflows or custom tooling.
DESCRIPTION
The yarn-why command is a powerful utility within the Yarn package manager, designed to help developers understand the dependency relationships within their JavaScript/TypeScript projects. When invoked with a specific package name, it traverses the project's dependency tree to identify and explain why that particular package has been installed. This includes both direct dependencies (explicitly listed in your `package.json`) and transitive dependencies (dependencies of your dependencies).
It's invaluable for debugging unexpected package installations, resolving version conflicts, identifying duplicate packages, or simply understanding the complex web of interconnected libraries that make up a modern web application. The output provides a clear path from a top-level dependency down to the queried package, making it easier to prune unnecessary dependencies or pinpoint the source of issues.
CAVEATS
Important Considerations:
It requires an existing node_modules directory or a Yarn Plug'n'Play (PnP) setup, along with a yarn.lock file, to accurately trace dependencies. Without these, the command cannot effectively determine the dependency tree.
The command's performance can vary on very large projects with extensive dependency trees, potentially taking longer to process.
It explains the path to a dependency, but not necessarily the reason a direct dependency was chosen by the project maintainers or application logic.
OUTPUT INTERPRETATION
The command's typical output presents a hierarchical view, illustrating the dependency chain that leads to the specified package. It often includes details such as the required version specified by the parent dependency and the actual resolved version, which helps in identifying potential version conflicts or understanding how a specific version was chosen. For example, it might show that your-app requires library-A, and library-A in turn requires target-package, thereby explaining target-package's presence in your project.
COMMON USE CASES
yarn-why is frequently utilized for a variety of tasks, including:
1. Debugging 'phantom dependencies,' which are packages that seem to be installed but are not explicitly listed as direct dependencies in your `package.json`.
2. Resolving version conflicts by understanding which parent dependency requires a problematic or incompatible version of a package.
3. Identifying unused or redundant packages by tracing back their origins and determining if they are still required by any active dependency.
4. Understanding the full impact of upgrading or removing a dependency, by seeing all the packages that rely on it.
HISTORY
Yarn was initially released by Facebook, Google, Exponent, and Tilde in 2016 to address shortcomings in the existing npm client, focusing on speed, reliability, and security. The `why` command was a crucial addition from its inception, providing a much-needed feature for deep dependency introspection that was less readily available or less intuitive in contemporary package managers. It has remained a core utility throughout Yarn's development, including the Yarn Berry (v2+) iterations, evolving to support new dependency management paradigms like Plug'n'Play (PnP) and respecting the `.pnp.cjs` file structure.
SEE ALSO
yarn-list(1), npm-ls(1), npm-explain(1), yarn-outdated(1)