@cryptotaxi247 / documentation-1
Code Commits Issues Pulls Sessions CI/CD
reggi/fix-transform-prettier
@reggi/path-to-regexp dependabot/npm_and_yarn/main/copy-to-clipboard-4.0.2 dependabot/npm_and_yarn/main/eslint-10.4.0 dependabot/npm_and_yarn/main/npmcli/eslint-config-7.0.0 dependabot/npm_and_yarn/main/proc-log-7.0.0 dependabot/npm_and_yarn/npm_and_yarn-826852524d dependabot/npm_and_yarn/npm_and_yarn-ab9a7f4bc2 deprecate-totp-2fa dhei/classic-tokens gat-bypass-2fa-docs jpg619/fix-accessibility-content-flow jpg619/version-bump-tar-2 kartykp/gat-bypass-2fa-docs kartykp/upgrade-path-to-regex main maitxn/version-bump-tar patch-1 reggi/cache-based-on-version reggi/dev-engines reggi/fix-transform-prettier reggi/overrides update-search-sensitivity
mdx 209 lines 5.44 KB
Raw
1 ---
2 title: npm-query
3 section: 1
4 description: Dependency selector query
5 github_repo: npm/cli
6 github_branch: release/v8
7 github_path: docs/lib/content/commands/npm-query.md
8 redirect_from:
9 - /cli-documentation/v8/cli-commands/npm-query
10 - /cli-documentation/v8/cli-commands/query
11 - /cli-documentation/v8/commands/npm-query
12 - /cli-documentation/v8/commands/query
13 - /cli-documentation/v8/npm-query
14 - /cli-documentation/v8/query
15 - /cli/v8/cli-commands/npm-query
16 - /cli/v8/cli-commands/query
17 - /cli/v8/commands/query
18 - /cli/v8/npm-query
19 - /cli/v8/query
20 ---
21
22 ### Synopsis
23
24 ```bash
25 npm query <selector>
26 ```
27
28 ### Description
29
30 The `npm query` command allows for usage of css selectors in order to retrieve an array of dependency objects.
31
32 ### Piping npm query to other commands
33
34 ```bash
35 # find all dependencies with postinstall scripts & uninstall them
36 npm query ":attr(scripts, [postinstall])" | jq 'map(.name)|join("\n")' -r | xargs -I {} npm uninstall {}
37
38 # find all git dependencies & explain who requires them
39 npm query ":type(git)" | jq 'map(.name)' | xargs -I {} npm why {}
40 ```
41
42 ### Extended Use Cases & Queries
43
44 ```stylus
45 // all deps
46 *
47
48 // all direct deps
49 :root > *
50
51 // direct production deps
52 :root > .prod
53
54 // direct development deps
55 :root > .dev
56
57 // any peer dep of a direct deps
58 :root > * > .peer
59
60 // any workspace dep
61 .workspace
62
63 // all workspaces that depend on another workspace
64 .workspace > .workspace
65
66 // all workspaces that have peer deps
67 .workspace:has(.peer)
68
69 // any dep named "lodash"
70 // equivalent to [name="lodash"]
71 #lodash
72
73 // any deps named "lodash" & within semver range ^"1.2.3"
74 #lodash@^1.2.3
75 // equivalent to...
76 [name="lodash"]:semver(^1.2.3)
77
78 // get the hoisted node for a given semver range
79 #lodash@^1.2.3:not(:deduped)
80
81 // querying deps with a specific version
82 #lodash@2.1.5
83 // equivalent to...
84 [name="lodash"][version="2.1.5"]
85
86 // has any deps
87 :has(*)
88
89 // deps with no other deps (ie. "leaf" nodes)
90 :empty
91
92 // manually querying git dependencies
93 [repository^=github:],
94 [repository^=git:],
95 [repository^=https://github.com],
96 [repository^=http://github.com],
97 [repository^=https://github.com],
98 [repository^=+git:...]
99
100 // querying for all git dependencies
101 :type(git)
102
103 // get production dependencies that aren't also dev deps
104 .prod:not(.dev)
105
106 // get dependencies with specific licenses
107 [license=MIT], [license=ISC]
108
109 // find all packages that have @ruyadorno as a contributor
110 :attr(contributors, [email=ruyadorno@github.com])
111 ```
112
113 ### Example Response Output
114
115 - 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
116
117 ```json
118 [
119 {
120 "name": "",
121 "version": "",
122 "description": "",
123 "homepage": "",
124 "bugs": {},
125 "author": {},
126 "license": {},
127 "funding": {},
128 "files": [],
129 "main": "",
130 "browser": "",
131 "bin": {},
132 "man": [],
133 "directories": {},
134 "repository": {},
135 "scripts": {},
136 "config": {},
137 "dependencies": {},
138 "devDependencies": {},
139 "optionalDependencies": {},
140 "bundledDependencies": {},
141 "peerDependencies": {},
142 "peerDependenciesMeta": {},
143 "engines": {},
144 "os": [],
145 "cpu": [],
146 "workspaces": {},
147 "keywords": [],
148 ...
149 },
150 ...
151 ```
152
153 ### Configuration
154
155 #### `global`
156
157 - Default: false
158 - Type: Boolean
159
160 Operates in "global" mode, so that packages are installed into the `prefix` folder instead of the current working directory. See [folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.
161
162 - packages are installed into the `{prefix}/lib/node_modules` folder, instead of the current working directory.
163 - bin files are linked to `{prefix}/bin`
164 - man pages are linked to `{prefix}/share/man`
165
166 #### `workspace`
167
168 - Default:
169 - Type: String (can be set multiple times)
170
171 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.
172
173 Valid values for the `workspace` config are either:
174
175 - Workspace names
176 - Path to a workspace directory
177 - Path to a parent workspace directory (will result in selecting all workspaces within that folder)
178
179 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.
180
181 This value is not exported to the environment for child processes.
182
183 #### `workspaces`
184
185 - Default: null
186 - Type: null or Boolean
187
188 Set to true to run the command in the context of **all** configured workspaces.
189
190 Explicitly setting this to false will cause commands like `install` to ignore workspaces altogether. When not set explicitly:
191
192 - 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.
193
194 This value is not exported to the environment for child processes.
195
196 #### `include-workspace-root`
197
198 - Default: false
199 - Type: Boolean
200
201 Include the workspace root when workspaces are enabled for a command.
202
203 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.
204
205 This value is not exported to the environment for child processes.
206
207 ## See Also
208
209 - [dependency selectors](/cli/v8/using-npm/dependency-selectors)