diff --git a/src/features/development.md b/src/features/development.md index 213d8c2b9..ad3d58e69 100644 --- a/src/features/development.md +++ b/src/features/development.md @@ -59,7 +59,7 @@ if (module.hot) { When using the dev server, only a single target can be built at once. By default, Parcel uses a development target that supports modern browsers. This means that transpilation of modern JavaScript syntax for older browsers is disabled. -If you need to test in a older browser, you can provide the `--target` CLI option to choose which of your targets to build. For example, to build the "legacy" target defined in your package.json, use `--target legacy`. If you don't have any explicit targets defined, and only have a `browserslist` in your package.json, you can use the implicit default target with `--target default`. This will result in your source code being transpiled just as it would be in production. +If you need to test in a older browser, you can provide the `--target` CLI option to choose which of your targets to build. For example, to build the "legacy" target defined in your `package.json`, use `--target legacy`. If you don't have any explicit targets defined, and only have a `browserslist` in your `package.json`, you can use the implicit default target with `--target default`. This will result in your source code being transpiled just as it would be in production. See the [Targets](/features/targets/) documentation for more information. @@ -70,7 +70,7 @@ In development, it can be frustrating to wait for your entire app to build befor You can use the `--lazy` CLI flag to tell Parcel to defer building files until they are requested in the browser, which can significantly reduce development build times. The server starts quickly, and when you navigate to a page for the first time, Parcel builds only the files necessary for that page. When you navigate to another page, that page will be built on demand. If you navigate back to a page that was previously built, it loads instantly. ```shell -parcel 'pages/*.html' --lazy +parcel --lazy 'pages/*.html' ``` This also works with dynamic `import()`, not just separate entries. So if you have a page with a dynamically loaded feature, that feature will not be built until it is activated. When it is requested, Parcel eagerly builds all of the dependencies as well, without waiting for them to be requested. @@ -90,13 +90,13 @@ Sometimes, you may need to use HTTPS during development. For example, you may ne To use an automatically generated self-signed certificate, use the `--https` CLI flag. The first time you load the page, you may need to manually trust this certificate in your browser. ```shell -parcel src/index.html --https +parcel --https src/index.html ``` To use a custom certificate, you’ll need to use the `--cert` and `--key` CLI options to specify the certificate file and private key respectively. ```shell -parcel src/index.html --cert certificate.cert --key private.key +parcel --cert certificate.cert --key private.key src/index.html ``` ## API proxy @@ -190,7 +190,7 @@ It is best practice to not place a Parcel project in a folder that is synced to ## Auto install -When you use a language or plugin that isn’t included by default, Parcel will automatically install the necessary dependencies into your project for you. For example, if you include a `.sass` file, Parcel will install the `@parcel/transformer-sass` plugin. When this happens, you'll see a message in the terminal, and the new dependency will be added to the `devDependencies` in your package.json. +When you use a language or plugin that isn’t included by default, Parcel will automatically install the necessary dependencies into your project for you. For example, if you include a `.sass` file, Parcel will install the `@parcel/transformer-sass` plugin. When this happens, you'll see a message in the terminal, and the new dependency will be added to the `devDependencies` in your `package.json`. Parcel automatically detects which package manager you use in your project based on the lock file. For example, if `yarn.lock` is found, then Yarn will be used to install packages. If no lock file is found, then the package manager is chosen based on what is installed on your system. The following package managers are currently supported, listed in priority order: diff --git a/src/features/targets.md b/src/features/targets.md index 26e8bce1c..884425666 100644 --- a/src/features/targets.md +++ b/src/features/targets.md @@ -11,7 +11,7 @@ Parcel can compile your source code in multiple different ways simultaneously. T ## Entries -“Entries” are the files that Parcel starts at when building your source code. They can be specified on the CLI, or using the `source` field in package.json. +“Entries” are the files that Parcel starts at when building your source code. They can be specified on the CLI, or using the `source` field in `package.json`. ### `$ parcel ` @@ -31,7 +31,7 @@ Entries may also be directories, in which case a `package.json` file containing ### `package.json#source` -The `source` field in package.json can specify one or more entry files. +The `source` field in `package.json` can specify one or more entry files. ```json { @@ -47,7 +47,7 @@ The `source` field in package.json can specify one or more entry files. ### `package.json#targets.*.source` -The `source` field within any target declared in package.json can specify one or more entry files that are specific to that target. For example, you could build your frontend and backend simultaneously, or your desktop and mobile apps. See below for details about configuring targets. +The `source` field within any target declared in `package.json` can specify one or more entry files that are specific to that target. For example, you could build your frontend and backend simultaneously, or your desktop and mobile apps. See below for details about configuring targets. ```json { @@ -72,7 +72,7 @@ By default, Parcel includes a single implicit target which outputs into the `dis $ parcel build src/index.html --dist-dir output ``` -The output directory can also be specified in package.json using the `targets` field. This will override the `--dist-dir` CLI option. +The output directory can also be specified in `package.json` using the `targets` field. This will override the `--dist-dir` CLI option. ```json { @@ -90,7 +90,7 @@ In addition to the output location, targets specify information about the “env #### `package.json#browserslist` -For browser targets, the `browserslist` field in package.json can be used to specify which browsers you support. You can query by usage statistics or by version ranges of specific browsers. See the [browserslist docs](https://github.com/browserslist/browserslist#full-list) for more information. +For browser targets, the `browserslist` field in `package.json` can be used to specify which browsers you support. You can query by usage statistics or by version ranges of specific browsers. See the [browserslist docs](https://github.com/browserslist/browserslist#full-list) for more information. ```json { @@ -100,7 +100,7 @@ For browser targets, the `browserslist` field in package.json can be used to spe #### `package.json#engines` -For Node.js and other targets, the `engines` field in package.json can be used to specify which versions you support. Engines are specified using a semver range. +For Node.js and other targets, the `engines` field in `package.json` can be used to specify which versions you support. Engines are specified using a semver range. ```json { @@ -135,13 +135,13 @@ is compiled to: This allows modern browsers that support ES modules to download a much smaller bundle, while legacy browsers are still supported using a fallback. This can significantly reduce bundle sizes and improve load times by avoiding transpilation of modern JavaScript syntax like classes, arrow functions, async/await, and more. -This happens automatically based on your browser targets, as declared in the `"browserslist"` field in your package.json. If no `browserslist` is declared, or all browser targets support ES modules natively, then a `nomodule` fallback will not be generated. +This happens automatically based on your browser targets, as declared in the `browserslist` field in your `package.json`. If no `browserslist` is declared, or all browser targets support ES modules natively, then a `nomodule` fallback will not be generated. ## Multiple targets You may have multiple targets in order to build your source code for multiple different environments simultaneously. For example, you could have “modern” and “legacy” targets for an app, or ES module and CommonJS targets for a library ([see below](#library-targets)). -Targets are configured using the `targets` field in package.json. Each target has a name, specified as a key under the `targets` field, and an associated configuration object. For example, the `engines` field within each target can be used to customize the environment it is compiled for. +Targets are configured using the `targets` field in `package.json`. Each target has a name, specified as a key under the `targets` field, and an associated configuration object. For example, the `engines` field within each target can be used to customize the environment it is compiled for. ```json { @@ -160,7 +160,7 @@ Targets are configured using the `targets` field in package.json. Each target ha } ``` -When multiple targets are specified, the outputs will be written to `dist/${targetName}` by default (e.g. `dist/modern` and `dist/legacy` in the above example). This can be customized using the `distDir` field in each target. Alternatively, if the target has only a single entry, an exact file name can be specified for the output using a top-level package.json field corresponding to the target name. +When multiple targets are specified, the outputs will be written to `dist/${targetName}` by default (e.g. `dist/modern` and `dist/legacy` in the above example). This can be customized using the `distDir` field in each target. Alternatively, if the target has only a single entry, an exact file name can be specified for the output using a top-level `package.json` field corresponding to the target name. ```json { @@ -247,7 +247,7 @@ Defines what type of module to output. - `esmodule` – an ES module using `import` and `export` statements. Could be loaded in a `