npm command-line interface

# npm-query

Dependency selector query

## Table of contents

- See Also

### Synopsis

    npm query <selector>

### Description

The `npm query` command allows for usage of css selectors in order to retrieve an array of dependency objects.

### Piping npm query to other commands

    # find all dependencies with postinstall scripts & uninstall them
    npm query ":attr(scripts, [postinstall])" | jq 'map(.name)|join("\n")' -r | xargs -I {} npm uninstall {}

    # find all git dependencies & explain who requires them
    npm query ":type(git)" | jq 'map(.name)' | xargs -I {} npm why {}

### Extended Use Cases & Queries

    // all deps
    *

    // all direct deps
    :root > *

    // direct production deps
    :root > .prod

    // direct development deps
    :root > .dev

    // any peer dep of a direct deps
    :root > * > .peer

    // any workspace dep
    .workspace

    // all workspaces that depend on another workspace
    .workspace > .workspace

    // all workspaces that have peer deps
    .workspace:has(.peer)

    // any dep named "lodash"
    // equivalent to [name="lodash"]
    #lodash

    // any deps named "lodash" & within semver range ^"1.2.3"
    #lodash@^1.2.3
    // equivalent to...
    [name="lodash"]:semver(^1.2.3)

    // get the hoisted node for a given semver range
    #lodash@^1.2.3:not(:deduped)

    // querying deps with a specific version
    #lodash@2.1.5
    // equivalent to...
    [name="lodash"][version="2.1.5"]

    // has any deps
    :has(*)

    // deps with no other deps (ie. "leaf" nodes)
    :empty

    // manually querying git dependencies
    [repository^=github:],
    [repository^=git:],
    [repository^=https://github.com],
    [repository^=http://github.com],
    [repository^=https://github.com],
    [repository^=+git:...]

    // querying for all git dependencies
    :type(git)

    // get production dependencies that aren't also dev deps
    .prod:not(.dev)

    // get dependencies with specific licenses
    [license=MIT], [license=ISC]

    // find all packages that have @ruyadorno as a contributor
    :attr(contributors, [email=ruyadorno@github.com])

### Example Response Output

- an array of dependency objects is returned which can contain multiple copies of the same package which may or may not have been linked or deduped

    [
      {
        "name": "",
        "version": "",
        "description": "",
        "homepage": "",
        "bugs": {},
        "author": {},
        "license": {},
        "funding": {},
        "files": [],
        "main": "",
        "browser": "",
        "bin": {},
        "man": [],
        "directories": {},
        "repository": {},
        "scripts": {},
        "config": {},
        "dependencies": {},
        "devDependencies": {},
        "optionalDependencies": {},
        "bundledDependencies": {},
        "peerDependencies": {},
        "peerDependenciesMeta": {},
        "engines": {},
        "os": [],
        "cpu": [],
        "workspaces": {},
        "keywords": [],
        ...
      },
      ...

### Configuration

#### `global`

- Default: false
- Type: Boolean

Operates in "global" mode, so that packages are installed into the `prefix` folder instead of the current working directory. See folders for more on the differences in behavior.

- packages are installed into the `{prefix}/lib/node_modules` folder, instead of the current working directory.
- bin files are linked to `{prefix}/bin`
- man pages are linked to `{prefix}/share/man`

#### `workspace`

- Default:
- Type: String (can be set multiple times)

Enable running a command in the context of the configured workspaces of the current project while filtering by running only the workspaces defined by this configuration option.

Valid values for the `workspace` config are either:

- Workspace names
- Path to a workspace directory
- Path to a parent workspace directory (will result in selecting all workspaces within that folder)

When set for the `npm init` command, this may be set to the folder of a workspace which does not yet exist, to create the folder and set it up as a brand new workspace within the project.

This value is not exported to the environment for child processes.

#### `workspaces`

- Default: null
- Type: null or Boolean

Set to true to run the command in the context of all configured workspaces.

Explicitly setting this to false will cause commands like `install` to ignore workspaces altogether. When not set explicitly:

- Commands that operate on the `node_modules` tree (install, update, etc.) will link workspaces into the `node_modules` folder. - Commands that do other things (test, exec, publish, etc.) will operate on the root project, unless one or more workspaces are specified in the `workspace` config.

This value is not exported to the environment for child processes.

#### `include-workspace-root`

- Default: false
- Type: Boolean

Include the workspace root when workspaces are enabled for a command.

When false, specifying individual workspaces via the `workspace` config, or all workspaces via the `workspaces` flag, will cause npm to operate only on the specified workspaces, and not on the root project.

This value is not exported to the environment for child processes.

## See Also

- dependency selectors