npm-query

Print direct dependencies

$ npm query ':root > *'

$ npm query ':root > .[prod|dev]'

$ npm query '#[package]'

$ npm query '#[package]@[semantic_version]'

$ npm query ':empty'

$ npm query ":attr(scripts, [postinstall])" | jq 'map(.name) | join("\n")' [[-r|--raw-output]] | xargs -I _ npm uninstall _

$ npm query ":type(git)" | jq 'map(.name)' | xargs -I _ npm why _

npm query <selector-string> [<options>]

--json
    Output results as a JSON array.

--include-workspace
    Include workspaces in the dependency graph traversal.

--workspace-root
    Restrict the query to only the root workspace.

--production, --omit=dev
    Only include production dependencies.

--development, --omit=prod
    Only include development dependencies.

--depth
    Limit the depth of dependency traversal.

--workspace
    Run the command in a specific workspace.

--workspaces
    Run the command in all configured workspaces.

--long
    Display extended information for each matched node.

--parseable
    Output a parseable format, often suitable for scripting.

--legend
    Display a legend explaining the output format symbols.

--filter
    Filter results based on property values (e.g., '--filter 'name=react'').

--query-root
    Start the query from a specific directory path instead of the current working directory.

--engine-strict
    Obey engine-strict rules when querying dependencies.

--prefer-online
    Prefer online version checks for faster results, even if offline cache is available.

--no-offline
    Force the command to operate online, ignoring any offline cache.

--offline
    Operate in offline mode, using only cached data.

--force
    Force actions, ignoring warnings or potential conflicts.

--no-unicode
    Do not use unicode characters in output, useful for terminals that don't support them.

--no-color
    Do not use colors in output.

The npm query command allows users to inspect and traverse the dependency graph of an npm project using CSS-like selectors. Introduced in npm@9, it provides a powerful way to filter, analyze, and understand the relationships between packages within a project, including workspaces. It can identify production dependencies, development dependencies, optional dependencies, peer dependencies, and more. The command leverages a dedicated query engine to efficiently navigate the node_modules tree and package.json configurations, returning a list of matched dependency nodes. This enables advanced use cases like finding specific versions, identifying extraneous packages, or understanding the impact of dependency changes.

The npm query command requires npm version 9.0.0 or higher. Its functionality relies on a robust internal query engine designed for npm's specific dependency graph structure, which may not behave identically to standard DOM CSS selectors in all edge cases. Querying extremely large or complex dependency trees can be resource-intensive and may take some time. The selector syntax, while CSS-like, has specific extensions and limitations tailored for npm packages.

npm query uses CSS-like selectors to navigate the dependency graph. Common selectors include:

<selector> <selector>: Descendant selector.
<selector> > <selector>: Child selector.
:root: Matches the project's root package.
:link: Matches packages that are symlinked (e.g., workspaces).
:prod / :production: Matches production dependencies.
:dev / :development: Matches development dependencies.
:optional: Matches optional dependencies.
:peer: Matches peer dependencies.
:bundle: Matches bundled dependencies.
:extraneous: Matches packages not explicitly listed in package.json.
:invalid: Matches packages that are invalid (e.g., missing).
:deduped: Matches deduped packages.
[name]: Matches by package name.
[version='1.0.0']: Matches by specific version.
[name^='foo']: Matches by regex on name (e.g., name starts with 'foo').
[homepage]: Matches if an attribute exists.
[name='foo'][version^='1.']: Multiple attribute matching.

By default, npm query outputs a human-readable tree-like structure.
The --json option provides a machine-readable JSON array of objects, each representing a matched node with detailed metadata.
The --long option adds more details to the default output, such as paths and license information.
The --parseable option provides a simplified, colon-separated output, useful for scripting.
The --legend option helps interpret the default output's symbols and colors.

The npm query command was officially introduced with the release of npm@9.0.0 in October 2022. It was developed to provide a standardized, powerful, and programmatic way to inspect and analyze the complex dependency graphs that characterize modern JavaScript projects, especially those leveraging npm workspaces. Prior to its introduction, users relied on combinations of npm ls, grep, and custom scripting to achieve similar analysis. npm query consolidates this functionality into a single, intuitive interface, built upon the underlying @npmcli/query package. Its development aimed to empower developers with better tools for understanding their project's dependencies for security audits, performance optimization, and general project maintenance.

npm(1), npm install(1), npm ls(1), npm view(1), npm exec(1)