codekingpro/portable-devtools

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