|
| 1 | +--- |
| 2 | +title: npm-pkg |
| 3 | +section: 1 |
| 4 | +description: Manages your package.json |
| 5 | +--- |
| 6 | + |
| 7 | +### Synopsis |
| 8 | + |
| 9 | +```bash |
| 10 | +npm pkg get [<field> [.<subfield> ...]] |
| 11 | +npm pkg set <field>=<value> [.<subfield>=<value> ...] |
| 12 | +npm pkg delete <field> [.<subfield> ...] |
| 13 | +``` |
| 14 | +
|
| 15 | +### Description |
| 16 | +
|
| 17 | +A command that automates the management of `package.json` files. |
| 18 | +`npm pkg` provide 3 different sub commands that allow you to modify or retrieve |
| 19 | +values for given object keys in your `packge.json`. |
| 20 | +
|
| 21 | +The syntax to retrieve and set fields is a dot separated representation of |
| 22 | +the nested object properties to be found within your `package.json`, it's the |
| 23 | +same notation used in [`npm view`](/commands/npm-view) to retrieve information |
| 24 | +from the registry manifest, below you can find more examples on how to use it. |
| 25 | +
|
| 26 | +Returned values are always in **json** format. |
| 27 | +
|
| 28 | +* `npm pkg get <field>` |
| 29 | +
|
| 30 | + Retrieves a value `key`, defined in your `package.json` file. |
| 31 | +
|
| 32 | + For example, in order to retrieve the name of the current package, you |
| 33 | + can run: |
| 34 | +
|
| 35 | + ```bash |
| 36 | + npm pkg get name |
| 37 | + ``` |
| 38 | +
|
| 39 | + It's also possible to retrieve multiple values at once: |
| 40 | +
|
| 41 | + ```bash |
| 42 | + npm pkg get name version |
| 43 | + ``` |
| 44 | +
|
| 45 | + You can view child fields by separating them with a period. To retrieve |
| 46 | + the value of a test `script` value, you would run the following command: |
| 47 | +
|
| 48 | + ```bash |
| 49 | + npm pkg get scripts.test |
| 50 | + ``` |
| 51 | +
|
| 52 | + For fields that are arrays, requesting a non-numeric field will return |
| 53 | + all of the values from the objects in the list. For example, to get all |
| 54 | + the contributor emails for a package, you would run: |
| 55 | +
|
| 56 | + ```bash |
| 57 | + npm pkg get contributors.email |
| 58 | + ``` |
| 59 | +
|
| 60 | + You may also use numeric indices in square braces to specifically select |
| 61 | + an item in an array field. To just get the email address of the first |
| 62 | + contributor in the list, you can run: |
| 63 | +
|
| 64 | + ```bash |
| 65 | + npm pkg get contributors[0].email |
| 66 | + ``` |
| 67 | +
|
| 68 | +* `npm pkg set <field>=<value>` |
| 69 | +
|
| 70 | + Sets a `value` in your `package.json` based on the `field` value. When |
| 71 | + saving to your `package.json` file the same set of rules used during |
| 72 | + `npm install` and other cli commands that touches the `package.json` file |
| 73 | + are used, making sure to respect the existing indentation and possibly |
| 74 | + applying some validation prior to saving values to the file. |
| 75 | +
|
| 76 | + The same syntax used to retrieve values from your package can also be used |
| 77 | + to define new properties or overriding existing ones, below are some |
| 78 | + examples of how the dot separated syntax can be used to edit your |
| 79 | + `package.json` file. |
| 80 | +
|
| 81 | + Defining a new bin named `mynewcommand` in your `package.json` that points |
| 82 | + to a file `cli.js`: |
| 83 | +
|
| 84 | + ```bash |
| 85 | + npm pkg set bin.mynewcommand=cli.js |
| 86 | + ``` |
| 87 | +
|
| 88 | + Setting multiple fields at once is also possible: |
| 89 | +
|
| 90 | + ```bash |
| 91 | + npm pkg set description='Awesome package' engines.node='>=10' |
| 92 | + ``` |
| 93 | +
|
| 94 | + It's also possible to add to array values, for example to add a new |
| 95 | + contributor entry: |
| 96 | +
|
| 97 | + ```bash |
| 98 | + npm pkg set contributors[0].name='Foo' contributors[0].email='[email protected]' |
| 99 | + ``` |
| 100 | +
|
| 101 | + It's also possible to parse values as json prior to saving them to your |
| 102 | + `package.json` file, for example in order to set a `"private": true` |
| 103 | + property: |
| 104 | +
|
| 105 | + ```bash |
| 106 | + npm pkg set private=true --json |
| 107 | + ``` |
| 108 | +
|
| 109 | + It also enables saving values as numbers: |
| 110 | +
|
| 111 | + ```bash |
| 112 | + npm pkg set tap.timeout=60 --json |
| 113 | + ``` |
| 114 | +
|
| 115 | +* `npm pkg delete <key>` |
| 116 | +
|
| 117 | + Deletes a `key` from your `package.json` |
| 118 | +
|
| 119 | + The same syntax used to set values from your package can also be used |
| 120 | + to remove existing ones. For example, in order to remove a script named |
| 121 | + build: |
| 122 | +
|
| 123 | + ```bash |
| 124 | + npm pkg delete scripts.build |
| 125 | + ``` |
| 126 | +
|
| 127 | +### Workspaces support |
| 128 | +
|
| 129 | +You can set/get/delete items across your configured workspaces by using the |
| 130 | +`workspace` or `workspaces` config options. |
| 131 | +
|
| 132 | +For example, setting a `funding` value across all configured workspaces |
| 133 | +of a project: |
| 134 | +
|
| 135 | +```bash |
| 136 | +npm pkg set funding=https://example.com --ws |
| 137 | +``` |
| 138 | +
|
| 139 | +When using `npm pkg get` to retrieve info from your configured workspaces, the |
| 140 | +returned result will be in a json format in which top level keys are the |
| 141 | +names of each workspace, the values of these keys will be the result values |
| 142 | +returned from each of the configured workspaces, e.g: |
| 143 | +
|
| 144 | +``` |
| 145 | +npm pkg get name version --ws |
| 146 | +{ |
| 147 | + "a": { |
| 148 | + "name": "a", |
| 149 | + "version": "1.0.0" |
| 150 | + }, |
| 151 | + "b": { |
| 152 | + "name": "b", |
| 153 | + "version": "1.0.0" |
| 154 | + } |
| 155 | +} |
| 156 | +``` |
| 157 | +
|
| 158 | +### Configuration |
| 159 | +
|
| 160 | +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START --> |
| 161 | +<!-- automatically generated, do not edit manually --> |
| 162 | +#### `force` |
| 163 | +
|
| 164 | +* Default: false |
| 165 | +* Type: Boolean |
| 166 | +
|
| 167 | +Removes various protections against unfortunate side effects, common |
| 168 | +mistakes, unnecessary performance degradation, and malicious input. |
| 169 | +
|
| 170 | +* Allow clobbering non-npm files in global installs. |
| 171 | +* Allow the `npm version` command to work on an unclean git repository. |
| 172 | +* Allow deleting the cache folder with `npm cache clean`. |
| 173 | +* Allow installing packages that have an `engines` declaration requiring a |
| 174 | + different version of npm. |
| 175 | +* Allow installing packages that have an `engines` declaration requiring a |
| 176 | + different version of `node`, even if `--engine-strict` is enabled. |
| 177 | +* Allow `npm audit fix` to install modules outside your stated dependency |
| 178 | + range (including SemVer-major changes). |
| 179 | +* Allow unpublishing all versions of a published package. |
| 180 | +* Allow conflicting peerDependencies to be installed in the root project. |
| 181 | +* Implicitly set `--yes` during `npm init`. |
| 182 | +* Allow clobbering existing values in `npm pkg` |
| 183 | +
|
| 184 | +If you don't have a clear idea of what you want to do, it is strongly |
| 185 | +recommended that you do not use this option! |
| 186 | +
|
| 187 | +#### `json` |
| 188 | +
|
| 189 | +* Default: false |
| 190 | +* Type: Boolean |
| 191 | +
|
| 192 | +Whether or not to output JSON data, rather than the normal output. |
| 193 | +
|
| 194 | +* In `npm pkg set` it enables parsing set values with JSON.parse() before |
| 195 | + saving them to your `package.json`. |
| 196 | +
|
| 197 | +Not supported by all npm commands. |
| 198 | +
|
| 199 | +#### `workspace` |
| 200 | +
|
| 201 | +* Default: |
| 202 | +* Type: String (can be set multiple times) |
| 203 | +
|
| 204 | +Enable running a command in the context of the configured workspaces of the |
| 205 | +current project while filtering by running only the workspaces defined by |
| 206 | +this configuration option. |
| 207 | +
|
| 208 | +Valid values for the `workspace` config are either: |
| 209 | +
|
| 210 | +* Workspace names |
| 211 | +* Path to a workspace directory |
| 212 | +* Path to a parent workspace directory (will result to selecting all of the |
| 213 | + nested workspaces) |
| 214 | +
|
| 215 | +When set for the `npm init` command, this may be set to the folder of a |
| 216 | +workspace which does not yet exist, to create the folder and set it up as a |
| 217 | +brand new workspace within the project. |
| 218 | +
|
| 219 | +This value is not exported to the environment for child processes. |
| 220 | +
|
| 221 | +#### `workspaces` |
| 222 | +
|
| 223 | +* Default: false |
| 224 | +* Type: Boolean |
| 225 | +
|
| 226 | +Enable running a command in the context of **all** the configured |
| 227 | +workspaces. |
| 228 | +
|
| 229 | +This value is not exported to the environment for child processes. |
| 230 | +
|
| 231 | +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END --> |
| 232 | +## See Also |
| 233 | +
|
| 234 | +* [npm install](/commands/npm-install) |
| 235 | +* [npm init](/commands/npm-init) |
| 236 | +* [npm config](/commands/npm-config) |
| 237 | +* [npm set-script](/commands/npm-set-script) |
| 238 | +* [workspaces](/using-npm/workspaces) |
0 commit comments