|
| 1 | +--- |
| 2 | +layout: layout.njk |
| 3 | +eleventyNavigation: |
| 4 | + title: ❓ package.json |
| 5 | + order: 1 |
| 6 | +summary: The targets object in package.json |
| 7 | +--- |
| 8 | + |
| 9 | +### `package.json` |
| 10 | + |
| 11 | +These are the fields that Parcel uses for its configuration: |
| 12 | + |
| 13 | +#### `main` / `module` / `browser` |
| 14 | + |
| 15 | +These are common fields used by other tools as well, |
| 16 | + |
| 17 | +{% sample %} |
| 18 | +{% samplefile "package.json" %} |
| 19 | + |
| 20 | +```json |
| 21 | +{ |
| 22 | + "main": "dist/main/index.js", |
| 23 | + "module": "dist/module/index.js", |
| 24 | + "browser": "dist/browser/index.js" |
| 25 | +} |
| 26 | +``` |
| 27 | + |
| 28 | +{% endsamplefile %} |
| 29 | +{% endsample %} |
| 30 | + |
| 31 | +They default to library mode (meaning they don't bundle dependencies): (see also [`targets`](#targets)) |
| 32 | + |
| 33 | +- `main` (and `module`) are the standard entry points to your library, `module` defaults to ESM module output. |
| 34 | +- `browser` is intended for a browser-specific build (e.g. without some native features). |
| 35 | + |
| 36 | +If one these fields is specified, Parcel will create a target for that field (no property in [`targets`](#targets) is needed) |
| 37 | + |
| 38 | +To make Parcel ignore one of these fields, specify `false` in `target.(main|browser|module)`: |
| 39 | + |
| 40 | +{% sample %} |
| 41 | +{% samplefile "package.json" %} |
| 42 | + |
| 43 | +```json |
| 44 | +{ |
| 45 | + "main": "unrelated.js", |
| 46 | + "targets": { |
| 47 | + "main": false |
| 48 | + } |
| 49 | +} |
| 50 | +``` |
| 51 | + |
| 52 | +{% endsamplefile %} |
| 53 | +{% endsample %} |
| 54 | + |
| 55 | +If the `browser` field is an [object](/features/module-resolution/#package.json-browser-field), `package.json#browser[pkgName]` can be used instead of `package.json#browser`. |
| 56 | + |
| 57 | +#### custom targets |
| 58 | + |
| 59 | +To create your own target (without any of the semantics of the [common target](#main-%2F-module-%2F-browser) described previously), add a top-level field with your target's name and output path. You also need to add it to [`targets`](#targets) to make Parcel recognize that field. |
| 60 | + |
| 61 | +{% sample %} |
| 62 | +{% samplefile "package.json" %} |
| 63 | + |
| 64 | +```json |
| 65 | +{ |
| 66 | + "app": "www/index.js", |
| 67 | + "targets": { |
| 68 | + "app": {} |
| 69 | + } |
| 70 | +} |
| 71 | +``` |
| 72 | + |
| 73 | +{% endsamplefile %} |
| 74 | +{% endsample %} |
| 75 | + |
| 76 | +#### `source` |
| 77 | + |
| 78 | +Specify the entry points for your source code which gets mapped to your targets, can be a string or an array. |
| 79 | + |
| 80 | +{% sample %} |
| 81 | +{% samplefile "package.json" %} |
| 82 | + |
| 83 | +```json |
| 84 | +{ |
| 85 | + "source": "src/index.js" |
| 86 | +} |
| 87 | +``` |
| 88 | + |
| 89 | +{% endsamplefile %} |
| 90 | + |
| 91 | +{% samplefile "package.json" %} |
| 92 | + |
| 93 | +```json |
| 94 | +{ |
| 95 | + "source": ["src/index.js", "src/index.html"] |
| 96 | +} |
| 97 | +``` |
| 98 | + |
| 99 | +{% endsamplefile %} |
| 100 | +{% endsample %} |
| 101 | + |
| 102 | +See [Specifying Entrypoints](#specifying-entrypoints). |
| 103 | + |
| 104 | +#### `targets` |
| 105 | + |
| 106 | +Targets are configured via the `package.json#targets` field. |
| 107 | + |
| 108 | +```json |
| 109 | +{ |
| 110 | + "app": "dist/browser/index.js", |
| 111 | + "appModern": "dist/browserModern/index.js", |
| 112 | + "targets": { |
| 113 | + "app": { |
| 114 | + "engines": { |
| 115 | + "browsers": "> 0.25%" |
| 116 | + } |
| 117 | + }, |
| 118 | + "appModern": { |
| 119 | + "engines": { |
| 120 | + "browsers": "Chrome 70" |
| 121 | + } |
| 122 | + } |
| 123 | + } |
| 124 | +} |
| 125 | +``` |
| 126 | + |
| 127 | +Each target has a name which corresponds to a top-level `package.json` field |
| 128 | +such as `package.json#main` or `package.json#app` which specify the primary |
| 129 | +entry point for that target. |
| 130 | + |
| 131 | +Each of those targets contains the target's environment configuration (all of these properties are optional): |
| 132 | + |
| 133 | +<div style="font-size: 0.9em"> |
| 134 | + |
| 135 | +| Option | Possible values | Description | |
| 136 | +| -------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 137 | +| `context` | [see below](#context) | In which runtime the bundles should run. | |
| 138 | +| `distDir` | `string` | Specify output folder (as opposed to output file) | |
| 139 | +| `engines` | [`package.json#engines`](#engines-%2F-browserslist) | Higher priority than `package.json#engines` | |
| 140 | +| `includeNodeModules` | [see below](#includenodemodules) | Whether to bundle all/none/some `node_module` dependencies | |
| 141 | +| `isLibrary` | `boolean` | Library as in "npm library" | |
| 142 | +| `minify` | `boolean` | Whether to enable minification (exact behaviour is determined by plugins). <br> Set by [`--no-minify`](/getting-started/cli/#parameters-specific-to-build) | |
| 143 | +| `outputFormat` | `'global' | 'esmodule' | 'commonjs'` | Which type of imports/exports should be emitted | |
| 144 | +| `publicUrl` | `string` | The public url of the bundle at runtime | |
| 145 | +| `scopeHoist` | `boolean` | Whether to enable scope hoisting <br> Needs to be `true` for ESM and CommonJS `outputFormat`. <br> Set by [`--no-scope-hoist`](/getting-started/cli/#parameters-specific-to-build) | |
| 146 | +| `sourceMap` | [see below](#sourcemap) | Enable/disable sourcemap and set options. <br> Overwritten by [`--no-source-maps`](/getting-started/cli/#general-parameters) | |
| 147 | + |
| 148 | +</div> |
| 149 | + |
| 150 | +However, a lot of the normal configuration for building a library is already provided by default for you: |
| 151 | + |
| 152 | +```cs |
| 153 | +targets = { |
| 154 | + main: { |
| 155 | + engines: { |
| 156 | + node: value("package.json#engines.node"), |
| 157 | + browsers: unless exists("package.json#browser") then value("package.json#browserlist") |
| 158 | + }, |
| 159 | + isLibrary: true |
| 160 | + }, |
| 161 | + module: { |
| 162 | + engines: { |
| 163 | + node: value("package.json#engines.node"), |
| 164 | + browsers: unless exists("package.json#browser") then value("package.json#browserlist") |
| 165 | + }, |
| 166 | + isLibrary: true |
| 167 | + }, |
| 168 | + browser: { |
| 169 | + engines: { |
| 170 | + browsers: value("package.json#browserslist") |
| 171 | + }, |
| 172 | + isLibrary: true |
| 173 | + }, |
| 174 | + ...value("package.json#targets"), |
| 175 | +} |
| 176 | +``` |
| 177 | + |
| 178 | +##### `context` |
| 179 | + |
| 180 | +Possible values are `'node' | 'browser' | 'web-worker' | 'service-worker' | 'electron-main' | 'electron-renderer'`. |
| 181 | + |
| 182 | +These values can be used by plugins (e.g. a service worker url should not contain a hash, a webworker can use `importScripts`). |
| 183 | + |
| 184 | +For the [common targets](#main-%2F-module-%2F-browser), these are inferred from the target: |
| 185 | + |
| 186 | +- The `main` target has the context `node` if there is `browser` target or `engines.node != null && engines.browsers == null`, and `browser` otherwise. |
| 187 | +- The `module` target has the context `node` if there is `browser` target and `browser` otherwise. |
| 188 | +- The `browser` target has context `browser`. |
| 189 | + |
| 190 | +##### `includeNodeModules` |
| 191 | + |
| 192 | +This fields defaults to `false` when `isLibrary` is true. Possible values are: |
| 193 | + |
| 194 | +- `false`: to include none `node_modules` package |
| 195 | +- an `array`: a list of packages names or wildcards to _include_ |
| 196 | +- an `object`: `includeNodeModules[pkgName] ?? true` determines if it is included. (e.g. `{ "lodash": false }`) |
| 197 | + |
| 198 | +##### `sourceMap` |
| 199 | + |
| 200 | +Can be a boolean (to simply enable / disable source maps) or an option (which is somewhat equivlant to `true`): |
| 201 | + |
| 202 | +| Option | Default value | Description | |
| 203 | +| ------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------- | |
| 204 | +| inline | `false` | Include the sourcemap as a data-url in the bundle (in the `sourceMappingURL`) | |
| 205 | +| inlineSources | `false` | Should the sourcemap contain the sources contents (otherwise, they will be loaded from `${sourceRoot}/$(name)`) | |
| 206 | +| sourceRoot | `path.relative(bundle, pojectRoot)` | Essentially the public url for the sources | |
| 207 | + |
| 208 | +The [--no-source-maps](getting-started/cli/#general-paramaters) CLI parameter sets the default value to `false` (as opposed to `true`). |
| 209 | + |
| 210 | +#### `engines` / `browserslist` |
| 211 | + |
| 212 | +These top-level fields set the default value for `target.*.engines.browsers` and `target.*.engines`, respectively. |
| 213 | + |
| 214 | +Specifies the [environment](#environments). |
| 215 | +{% sample %} |
| 216 | +{% samplefile "package.json" %} |
| 217 | + |
| 218 | +```json |
| 219 | +{ |
| 220 | + "browserslist": ["> 0.2%", "not dead"] |
| 221 | +} |
| 222 | +``` |
| 223 | + |
| 224 | +{% endsamplefile %} |
| 225 | +{% samplefile "package.json" %} |
| 226 | + |
| 227 | +```json |
| 228 | +{ |
| 229 | + "engines": { |
| 230 | + "node": ">=4.x", |
| 231 | + "electron": ">=2.x", |
| 232 | + "browsers": "> 0.25%" |
| 233 | + } |
| 234 | +} |
| 235 | +``` |
| 236 | + |
| 237 | +{% endsamplefile %} |
| 238 | +{% endsample %} |
| 239 | + |
| 240 | +#### `alias` |
| 241 | + |
| 242 | +See [Module Resolution](/features/module-resolution/#aliases) |
0 commit comments