@cryptotaxi247 / documentation
Code Commits Issues Pulls Sessions CI/CD
kartykp/upgrade-path-to-regex
@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 272 lines 7.75 KB
Raw
1 ---
2 title: npm-query
3 section: 1
4 description: Dependency selector query
5 github_repo: npm/cli
6 github_branch: latest
7 github_path: docs/lib/content/commands/npm-query.md
8 redirect_from:
9 - /cli-commands/npm-query
10 - /cli-commands/query
11 - /cli-documentation/cli-commands/npm-query
12 - /cli-documentation/cli-commands/query
13 - /cli-documentation/commands/npm-query
14 - /cli-documentation/commands/query
15 - /cli-documentation/npm-query
16 - /cli-documentation/query
17 - /cli-documentation/v10/cli-commands/npm-query
18 - /cli-documentation/v10/cli-commands/query
19 - /cli-documentation/v10/commands/npm-query
20 - /cli-documentation/v10/commands/query
21 - /cli-documentation/v10/npm-query
22 - /cli-documentation/v10/query
23 - /cli/cli-commands/npm-query
24 - /cli/cli-commands/query
25 - /cli/commands/npm-query
26 - /cli/commands/query
27 - /cli/npm-query
28 - /cli/query
29 - /cli/v10/cli-commands/npm-query
30 - /cli/v10/cli-commands/query
31 - /cli/v10/commands/query
32 - /cli/v10/npm-query
33 - /cli/v10/query
34 - /commands/npm-query
35 - /commands/query
36 ---
37
38 ### Synopsis
39
40 ```bash
41 npm query <selector>
42 ```
43
44 ### Description
45
46 The `npm query` command allows for usage of css selectors in order to retrieve an array of dependency objects.
47
48 ### Piping npm query to other commands
49
50 ```bash
51 # find all dependencies with postinstall scripts & uninstall them
52 npm query ":attr(scripts, [postinstall])" | jq 'map(.name)|join("\n")' -r | xargs -I {} npm uninstall {}
53
54 # find all git dependencies & explain who requires them
55 npm query ":type(git)" | jq 'map(.name)' | xargs -I {} npm why {}
56 ```
57
58 ### Extended Use Cases & Queries
59
60 ```stylus
61 // all deps
62 *
63
64 // all direct deps
65 :root > *
66
67 // direct production deps
68 :root > .prod
69
70 // direct development deps
71 :root > .dev
72
73 // any peer dep of a direct deps
74 :root > * > .peer
75
76 // any workspace dep
77 .workspace
78
79 // all workspaces that depend on another workspace
80 .workspace > .workspace
81
82 // all workspaces that have peer deps
83 .workspace:has(.peer)
84
85 // any dep named "lodash"
86 // equivalent to [name="lodash"]
87 #lodash
88
89 // any deps named "lodash" & within semver range ^"1.2.3"
90 #lodash@^1.2.3
91 // equivalent to...
92 [name="lodash"]:semver(^1.2.3)
93
94 // get the hoisted node for a given semver range
95 #lodash@^1.2.3:not(:deduped)
96
97 // querying deps with a specific version
98 #lodash@2.1.5
99 // equivalent to...
100 [name="lodash"][version="2.1.5"]
101
102 // has any deps
103 :has(*)
104
105 // deps with no other deps (ie. "leaf" nodes)
106 :empty
107
108 // manually querying git dependencies
109 [repository^=github:],
110 [repository^=git:],
111 [repository^=https://github.com],
112 [repository^=http://github.com],
113 [repository^=https://github.com],
114 [repository^=+git:...]
115
116 // querying for all git dependencies
117 :type(git)
118
119 // get production dependencies that aren't also dev deps
120 .prod:not(.dev)
121
122 // get dependencies with specific licenses
123 [license=MIT], [license=ISC]
124
125 // find all packages that have @ruyadorno as a contributor
126 :attr(contributors, [email=ruyadorno@github.com])
127 ```
128
129 ### Example Response Output
130
131 - 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
132
133 ```json
134 [
135 {
136 "name": "",
137 "version": "",
138 "description": "",
139 "homepage": "",
140 "bugs": {},
141 "author": {},
142 "license": {},
143 "funding": {},
144 "files": [],
145 "main": "",
146 "browser": "",
147 "bin": {},
148 "man": [],
149 "directories": {},
150 "repository": {},
151 "scripts": {},
152 "config": {},
153 "dependencies": {},
154 "devDependencies": {},
155 "optionalDependencies": {},
156 "bundledDependencies": {},
157 "peerDependencies": {},
158 "peerDependenciesMeta": {},
159 "engines": {},
160 "os": [],
161 "cpu": [],
162 "workspaces": {},
163 "keywords": [],
164 ...
165 },
166 ...
167 ```
168
169 ### Expecting a certain number of results
170
171 One common use of `npm query` is to make sure there is only one version of a certain dependency in your tree. This is especially common for ecosystems like that rely on `typescript` where having state split across two different but identically-named packages causes bugs. You can use the `--expect-results` or `--expect-result-count` in your setup to ensure that npm will exit with an exit code if your tree doesn't look like you want it to.
172
173 ```sh
174 $ npm query '#react' --expect-result-count=1
175 ```
176
177 Perhaps you want to quickly check if there are any production dependencies that could be updated:
178
179 ```sh
180 $ npm query ':root>:outdated(in-range).prod' --no-expect-results
181 ```
182
183 ### Package lock only mode
184
185 If package-lock-only is enabled, only the information in the package lock (or shrinkwrap) is loaded. This means that information from the package.json files of your dependencies will not be included in the result set (e.g. description, homepage, engines).
186
187 ### Configuration
188
189 #### `global`
190
191 - Default: false
192 - Type: Boolean
193
194 Operates in "global" mode, so that packages are installed into the `prefix` folder instead of the current working directory. See [folders](/cli/v10/configuring-npm/folders) for more on the differences in behavior.
195
196 - packages are installed into the `{prefix}/lib/node_modules` folder, instead of the current working directory.
197 - bin files are linked to `{prefix}/bin`
198 - man pages are linked to `{prefix}/share/man`
199
200 #### `workspace`
201
202 - Default:
203 - Type: String (can be set multiple times)
204
205 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.
206
207 Valid values for the `workspace` config are either:
208
209 - Workspace names
210 - Path to a workspace directory
211 - Path to a parent workspace directory (will result in selecting all workspaces within that folder)
212
213 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.
214
215 This value is not exported to the environment for child processes.
216
217 #### `workspaces`
218
219 - Default: null
220 - Type: null or Boolean
221
222 Set to true to run the command in the context of **all** configured workspaces.
223
224 Explicitly setting this to false will cause commands like `install` to ignore workspaces altogether. When not set explicitly:
225
226 - 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.
227
228 This value is not exported to the environment for child processes.
229
230 #### `include-workspace-root`
231
232 - Default: false
233 - Type: Boolean
234
235 Include the workspace root when workspaces are enabled for a command.
236
237 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.
238
239 This value is not exported to the environment for child processes.
240
241 #### `package-lock-only`
242
243 - Default: false
244 - Type: Boolean
245
246 If set to true, the current operation will only use the `package-lock.json`, ignoring `node_modules`.
247
248 For `update` this means only the `package-lock.json` will be updated, instead of checking `node_modules` and downloading dependencies.
249
250 For `list` this means the output will be based on the tree described by the `package-lock.json`, rather than the contents of `node_modules`.
251
252 #### `expect-results`
253
254 - Default: null
255 - Type: null or Boolean
256
257 Tells npm whether or not to expect results from the command. Can be either true (expect some results) or false (expect no results).
258
259 This config can not be used with: `expect-result-count`
260
261 #### `expect-result-count`
262
263 - Default: null
264 - Type: null or Number
265
266 Tells to expect a specific number of results from the command.
267
268 This config can not be used with: `expect-results`
269
270 ## See Also
271
272 - [dependency selectors](/cli/v10/using-npm/dependency-selectors)