codekingpro/portable-devtools

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