@cryptotaxi247 / documentation-1
Code Commits Issues Pulls Sessions CI/CD
@reggi/path-to-regexp
@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 256 lines 7.29 KB
Raw
1 ---
2 title: npm-query
3 section: 1
4 description: Dependency selector query
5 github_repo: npm/cli
6 github_branch: release/v10
7 github_path: docs/lib/content/commands/npm-query.md
8 redirect_from:
9 - /cli-documentation/v10/cli-commands/npm-query
10 - /cli-documentation/v10/cli-commands/query
11 - /cli-documentation/v10/commands/npm-query
12 - /cli-documentation/v10/commands/query
13 - /cli-documentation/v10/npm-query
14 - /cli-documentation/v10/query
15 - /cli/v10/cli-commands/npm-query
16 - /cli/v10/cli-commands/query
17 - /cli/v10/commands/query
18 - /cli/v10/npm-query
19 - /cli/v10/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 ### Expecting a certain number of results
154
155 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.
156
157 ```sh
158 $ npm query '#react' --expect-result-count=1
159 ```
160
161 Perhaps you want to quickly check if there are any production dependencies that could be updated:
162
163 ```sh
164 $ npm query ':root>:outdated(in-range).prod' --no-expect-results
165 ```
166
167 ### Package lock only mode
168
169 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).
170
171 ### Configuration
172
173 #### `global`
174
175 - Default: false
176 - Type: Boolean
177
178 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.
179
180 - packages are installed into the `{prefix}/lib/node_modules` folder, instead of the current working directory.
181 - bin files are linked to `{prefix}/bin`
182 - man pages are linked to `{prefix}/share/man`
183
184 #### `workspace`
185
186 - Default:
187 - Type: String (can be set multiple times)
188
189 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.
190
191 Valid values for the `workspace` config are either:
192
193 - Workspace names
194 - Path to a workspace directory
195 - Path to a parent workspace directory (will result in selecting all workspaces within that folder)
196
197 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.
198
199 This value is not exported to the environment for child processes.
200
201 #### `workspaces`
202
203 - Default: null
204 - Type: null or Boolean
205
206 Set to true to run the command in the context of **all** configured workspaces.
207
208 Explicitly setting this to false will cause commands like `install` to ignore workspaces altogether. When not set explicitly:
209
210 - 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.
211
212 This value is not exported to the environment for child processes.
213
214 #### `include-workspace-root`
215
216 - Default: false
217 - Type: Boolean
218
219 Include the workspace root when workspaces are enabled for a command.
220
221 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.
222
223 This value is not exported to the environment for child processes.
224
225 #### `package-lock-only`
226
227 - Default: false
228 - Type: Boolean
229
230 If set to true, the current operation will only use the `package-lock.json`, ignoring `node_modules`.
231
232 For `update` this means only the `package-lock.json` will be updated, instead of checking `node_modules` and downloading dependencies.
233
234 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`.
235
236 #### `expect-results`
237
238 - Default: null
239 - Type: null or Boolean
240
241 Tells npm whether or not to expect results from the command. Can be either true (expect some results) or false (expect no results).
242
243 This config can not be used with: `expect-result-count`
244
245 #### `expect-result-count`
246
247 - Default: null
248 - Type: null or Number
249
250 Tells to expect a specific number of results from the command.
251
252 This config can not be used with: `expect-results`
253
254 ## See Also
255
256 - [dependency selectors](/cli/v10/using-npm/dependency-selectors)