\n\n[](#backers) [](#sponsors)\n[](https://dev.azure.com/devongovett/devongovett/_build/latest?definitionId=1)\n[](https://codecov.io/github/parcel-bundler/parcel/)\n[](https://david-dm.org/parcel-bundler/parcel)\n[](https://www.npmjs.com/package/parcel-bundler)\n[](https://www.npmjs.com/package/parcel-bundler)\n[](https://spectrum.chat/parcel)\n[](https://twitter.com/parceljs)\n\n## Features\n\n- 🚀 **Blazing fast** bundle times - multicore compilation, and a filesystem cache for fast rebuilds even after a restart.\n- 📦 Out of the box support for JS, CSS, HTML, file assets, and more - **no plugins to install**.\n- 🐠 **Automatically transforms modules** using Babel, PostCSS, and PostHTML when needed - even `node_modules`.\n- ✂️ Zero configuration **code splitting** using dynamic `import()` statements.\n- 🔥 Built in support for **hot module replacement**\n- 🚨 Friendly error logging experience - syntax highlighted code frames help pinpoint the problem.\n\n## Getting Started\n\nBefore we get started, you'll need to install Node and Yarn (or npm) and create\na `package.json` for your project if you haven't already.\n\n```sh\nyarn init\n```\n\nThen with Yarn you can install `parcel` into your app:\n\n```sh\nyarn add --dev parcel@next\n```\n\nFrom there you just need to point Parcel at some of your entry files. Like if\nyou're building a website, an `index.html` file:\n\n```html\n\n\n \n \n My First Parcel App\n \n \n
Hello, World!
\n \n\n```\n\nNow if you just run:\n\n```sh\nyarn parcel index.html\n```\n\nYou should get a URL that looks something like: `http://localhost:1234/`\n\nNext you can start adding dependencies by specifying them in your code (however\nyour language specifies other assets). So for HTML we could create a\n`styles.css` file next to our `index.html` file and include it with a ``\ntag.\n\n```css\nh1 {\n color: hotpink;\n font-family: cursive;\n}\n```\n\n```html\n\n\n \n \n My First Parcel App\n \n \n \n
Hello, World!
\n \n\n```\n\nIf we want parcel to update our changes in the browser without refreshing the page,\nwe need to add at least a dummy javascript file e.g. `app.js` next to our `index.html`.\nThis file allows parcel to inject all the necessary code to show your changes.\nThis file will later contain your javascript application.\n\n```javascript\nconsole.log(\"Hello World\");\n```\n\n```html\n\n\n \n \n My First Parcel App\n \n \n \n \n
Hello, World!
\n \n\n```\n\n## Documentation\n\n\n\n\n\n- [Introduction](#introduction)\n- [Parcel CLI](#parcel-cli)\n - [CLI Args & Flags](#cli-args--flags)\n - [`parcel serve`](#parcel-serve)\n - [`parcel watch`](#parcel-watch)\n - [`parcel build`](#parcel-build)\n - [`[...entries]`](#entries)\n - [`--target [name]`](#--target-name)\n - [`--open, -o [browser]`](#--open--o-browser)\n - [`--host `](#--host-host)\n - [`--port , -p`](#--port-port--p)\n - [`--https`](#--https)\n - [`--cert `](#--cert-path)\n - [`--key `](#--key-path)\n - [`--cache-dir `, `--no-cache`](#--cache-dir-dir---no-cache)\n - [`--hot`, `--no-hot`](#--hot---no-hot)\n - [`--hot-host `](#--hot-host-hostname)\n - [`--hot-port `](#--hot-port-port)\n - [`--[no-]source-maps`](#--no-source-maps)\n - [`--autoinstall [npm/yarn], --no-autoinstall`](#--autoinstall-npmyarn---no-autoinstall)\n - [`--log-level `](#--log-level-level)\n - [`--version, -v, -V`](#--version--v--v)\n - [`--help, -h`](#--help--h)\n- [Parcel Config](#parcel-config)\n - [Configuring external tools](#configuring-external-tools)\n - [Configuring Parcel](#configuring-parcel)\n - [`package.json`](#packagejson)\n - [`package.json#name`](#packagejsonname)\n - [`package.json#version`](#packagejsonversion)\n - [`package.json#main`](#packagejsonmain)\n - [`package.json#module`](#packagejsonmodule)\n - [`package.json#browser`](#packagejsonbrowser)\n - [`package.json#source`](#packagejsonsource)\n - [`package.json#browserslist`](#packagejsonbrowserslist)\n - [`package.json#engines`](#packagejsonengines)\n - [`package.json#targets`](#packagejsontargets)\n - [`package.json#alias`](#packagejsonalias)\n - [`.parcelrc`](#parcelrc)\n - [Glob maps in `.parcelrc`](#glob-maps-in-parcelrc)\n - [`.parcelrc#extends`](#parcelrcextends)\n - [`.parcelrc#resolvers`](#parcelrcresolvers)\n - [`.parcelrc#transforms`](#parcelrctransforms)\n - [`.parcelrc#bundler`](#parcelrcbundler)\n - [`.parcelrc#namers`](#parcelrcnamers)\n - [`.parcelrc#runtimes`](#parcelrcruntimes)\n - [`.parcelrc#packagers`](#parcelrcpackagers)\n - [`.parcelrc#optimizers`](#parcelrcoptimizers)\n - [`.parcelrc#reporters`](#parcelrcreporters)\n - [`.parcelrc#validators`](#parcelrcvalidators)\n- [Parcel Architecture](#parcel-architecture)\n - [Phases of Parcel](#phases-of-parcel)\n - [Asset Graph](#asset-graph)\n - [Bundles](#bundles)\n - [Sources](#sources)\n - [Targets](#targets)\n - [Target Configuration](#target-configuration)\n - [Environments](#environments)\n - [Caching](#caching)\n- [Asset Resolution](#asset-resolution)\n - [Local Paths](#local-paths)\n - [Package Paths](#package-paths)\n - [URLs](#urls)\n - [Tilde Paths](#tilde-paths)\n - [Aliases](#aliases)\n- [Plugins](#plugins)\n - [Resolvers](#resolvers)\n - [Transforms](#transforms)\n - [Bundlers](#bundlers)\n - [Namers](#namers)\n - [Runtimes](#runtimes)\n - [Packagers](#packagers)\n - [Optimizers](#optimizers)\n - [Reporters](#reporters)\n - [Validators](#validators)\n- [Creating Plugins](#creating-plugins)\n - [Naming](#naming)\n - [Versioning](#versioning)\n - [Engines](#engines)\n- [Plugin APIs](#plugin-apis)\n - [Resolvers](#resolvers-1)\n - [Transforms](#transforms-1)\n - [Bundler](#bundler)\n - [Namers](#namers-1)\n - [Runtimes](#runtimes-1)\n - [Packagers](#packagers-1)\n - [Optimizers](#optimizers-1)\n - [Reporters](#reporters-1)\n - [Validators](#validators-1)\n\n\n\n## Introduction\n\nParcel is a compiler for all your code, regardless of the language or toolchain.\n\nParcel takes all of your files and dependencies, transforms them, and merges\nthem together into a smaller set of output files that can be used to run your\ncode.\n\nParcel supports many different languages and file types out of the box, from\nweb technologies like HTML, CSS, and JavaScript, to lower level languages like\nRust, and anything that compiles to WebAssembly (WASM), to assets like images,\nfonts, videos, and more.\n\nParcel makes your code portable, you can build your code for different\nenvironments, for the web for your server, or for an app. You can even build\nmultiple targets at once and have them live update as you make changes.\n\nParcel is fast and predictable. It compiles all of your files in isolation in\nparallel inside workers, caching all of them as it goes along. Caches are\nstable across machines and are only affected by the files and configs within\nyour project (unless you want to pass specific environment variables).\n\n## Parcel CLI\n\nThe Parcel CLI is built into the main `parcel` package. While you can install\nit globally and run it, it is much better to install it locally into your\nproject as a dev dependency.\n\n```sh\nyarn add --dev parcel@next\n```\n\nYou should also add some \"scripts\" to your `package.json` to run it easier.\n\n```json\n{\n \"name\": \"my-project\",\n \"scripts\": {\n \"build\": \"parcel build index.html\",\n \"start\": \"parcel serve index.html\"\n },\n \"devDependencies\": {\n \"@unofficial-parcel-nightly/parcel\": \"latest\"\n }\n}\n```\n\nNow you can run `yarn build` to bundle your project for production and\n`yarn start` to dev on your project.\n\n### CLI Args & Flags\n\nUsage:\n\n```sh\n$ parcel [command] [...entries] [...flags]\n```\n\n#### `parcel serve`\n\nServe assets on a local server\n\n#### `parcel watch`\n\nWatch and rebuild code on file changes.\n\n#### `parcel build`\n\nBuild code once, in production mode.\n\n#### `[...entries]`\n\nEntry files to start bundling, these will be preserved as entry points in the\noutput. Defaults to `package.json#source`, falling back to `src/index.*` or\n`index.*`. See [#Entries](#entries-sources-targets-environment).\n\n#### `--target [name]`\n\nSpecifies a specific target to build. If unspecified, Parcel builds all\ntargets specified in package.json. See [#Targets](#targets).\n\n#### `--open, -o [browser]`\n\nOpen your local server in a browser. You can optionally pass the name of the\nbrowser you want to open, otherwise it will use your default browser.\n\n#### `--host `\n\nConfigure the host to serve assets on. The default is to listen on all interfaces.\n\n#### `--port , -p`\n\nConfigure the port to serve assets on. Alternatively you can use the `$PORT`\nenvironment variable.\n\n#### `--https`\n\nThis will generate a local certificate (which will be untrusted by your\nbrowser, you'll need to approve it) and serve your assets over `https://`\n\n##### `--cert `\n\nSpecify the filepath to your SSL certificate when using `--https`.\n\n##### `--key `\n\nSpecify the filepath to your SSL key when using `--https`.\n\n#### `--cache-dir `, `--no-cache`\n\nConfigure the cache directory with `--cache ` or disable it altogether\nwith `--no-cache`.\n\n#### `--hot`, `--no-hot`\n\nTurn hot reloading on or off.\n\n##### `--hot-host `\n\nConfigure the hot reloading hostname.\n\n##### `--hot-port `\n\nConfigure the hot reloading port.\n\n#### `--[no-]source-maps`\n\nTurn source maps on or off. Source maps are turned on by default.\n\n#### `--autoinstall [npm/yarn], --no-autoinstall`\n\nWhen enabled, whenever Parcel discovers a dependency that isn't installed it\nwill attempt to install it with either npm or Yarn (defaults to npm unless a\n`yarn.lock` exists).\n\n#### `--log-level `\n\nSet the log level, either either \"none\", \"error\", \"warn\", \"info\", or \"verbose\".\nThe default is \"info\".\n\n#### `--version, -v, -V`\n\nReturn the current version of Parcel.\n\n#### `--help, -h`\n\nGet help with the CLI.\n\n## Parcel Config\n\nParcel has always and will always work out of the box for many projects with\nzero configuration. It should always be extremely simple to get started. But if\nyou do want more control, we give you the tools to do so.\n\n### Configuring external tools\n\nA huge part of what Parcel does is run other tools over your code. Instead of\npulling all that configuration into Parcel, we make use of their own\nconfiguration systems. So if you're using Babel, you should just use `.babelrc`\nfiles to configure it.\n\nWhen we do need to introduce config, we create tool specific config files in\norder to do so.\n\n### Configuring Parcel\n\nWhen you do need to configure Parcel, it will be in one of 3 places.\n\n- If you need to configure the CLI, it will be a CLI flag\n- If you need to configure your package, it will be in the `package.json`\n- If you need to configure something with your files or the Parcel asset\n pipeline, it will be in `.parcelrc`\n\n### `package.json`\n\n[todo]\n\n```json\n{\n \"name\": \"foo\",\n \"main\": \"dist/main/index.js\",\n \"module\": \"dist/module/index.js\",\n \"browser\": \"dist/browser/index.js\",\n \"browserslist\": [\"> 1%\", \"not dead\"],\n \"engines\": {\n \"node\": \">=4.x\"\n },\n \"source\": \"src/index.js\",\n \"targets\": {\n \"main\": {\n \"node\": [\"^4.0.0\"]\n },\n \"module\": {\n \"node\": [\"^8.0.0\"]\n },\n \"browser\": {\n \"browsers\": [\"> 1%\", \"not dead\"]\n }\n },\n \"alias\": {\n \"react\": \"preact-compat\",\n \"react-dom\": \"preact-compat\"\n }\n}\n```\n\n#### `package.json#name`\n\n**(Required)** The name of the package is always required in order to be\nconsidered a valid `package.json`.\n\n```json\n{\n \"name\": \"my-package\"\n}\n```\n\n#### `package.json#version`\n\n**(Required)** All packages inside `node_modules` must have a `package.json#version`.\n\n```json\n{\n \"version\": \"1.0.0\"\n}\n```\n\n#### `package.json#main`\n\nThis is the \"main\" target's entry point for the package, by default in library mode (doesn't bundle dependencies).\n\n```json\n{\n \"main\": \"dist/main/index.js\"\n}\n```\n\nSee [Targets](#targets)\n\n#### `package.json#module`\n\nThis is the \"module\" target's entry point for the package, by default in library mode (doesn't bundle dependencies).\n\n```json\n{\n \"module\": \"dist/module/index.js\"\n}\n```\n\nSee [Targets](#targets)\n\n#### `package.json#browser`\n\nThis is the \"browser\" target's entry point for the package, by default in library mode (doesn't bundle dependencies).\n\n```json\n{\n \"browser\": \"dist/browser/index.js\"\n}\n```\n\nSee [Targets](#targets)\n\n#### `package.json#source`\n\nSpecify the entry points for your source code which gets mapped to your\ntargets.\n\n```json\n{\n \"source\": \"src/index.js\",\n \"source\": [\"src/index.js\", \"src/index.html\"]\n}\n```\n\nSee [Sources](#sources)\n\n#### `package.json#browserslist`\n\nAs specified by Browserslist, this field is for specifying which transforms\nshould be applied to browser bundles.\n\n```json\n{\n \"browserslist\": [\"> 0.2%\", \"not dead\"]\n}\n```\n\nSee [Environments](#environments)\n\n#### `package.json#engines`\n\nSpecify what versions of what engines you want to support.\n\n```json\n{\n \"engines\": {\n \"node\": \">=4.x\",\n \"electron\": \">=2.x\"\n }\n}\n```\n\nSee [Environments](#environments)\n\n#### `package.json#targets`\n\nConfiguration for individual targets.\n\n```json\n{\n \"targets\": {\n \"main\": {\n \"engines\": {\n \"node\": \">=4.x\",\n \"electron\": \">=2.x\"\n },\n },\n \"browser\": {\n \"engines\": {\n \"browsers\": [\"> 1%\", \"not dead\"]\n }\n }\n }\n}\n```\n\nSee [Targets](#targets)\n\n#### `package.json#alias`\n\nAliases asset names/paths to other assets.\n\n```json\n{\n \"alias\": {\n \"react\": \"preact-compat\",\n \"react-dom\": \"preact-compat\"\n }\n}\n```\n\nSee [Aliases](#aliases)\n\n### `.parcelrc`\n\nYour `.parcelrc` file will likely contain just a few fields (if you have one at\nall), but here's an example of a `.parcelrc` file that contains every field:\n\n```json\n{\n \"extends\": [\"@unofficial-parcel-nightly/parcel-config-default\"],\n \"resolvers\": [\"@unofficial-parcel-nightly/parcel-resolver-default\"],\n \"transforms\": {\n \"*.vue\": [\"@parcel/transformer-vue\"],\n \"*.scss\": [\"@unofficial-parcel-nightly/parcel-transformer-sass\"],\n \"*.js\": [\"@unofficial-parcel-nightly/parcel-transformer-babel\"],\n \"*.css\": [\"@unofficial-parcel-nightly/parcel-transformer-postcss\"],\n \"*.html\": [\"@unofficial-parcel-nightly/parcel-transformer-posthtml\"]\n },\n \"bundler\": \"@unofficial-parcel-nightly/parcel-bundler-default\",\n \"namers\": [\"@unofficial-parcel-nightly/parcel-namer-default\"],\n \"runtimes\": {\n \"browser\": [\"@unofficial-parcel-nightly/parcel-runtime-js\", \"@unofficial-parcel-nightly/parcel-runtime-browser-hmr\"],\n \"node\": [\"@unofficial-parcel-nightly/parcel-runtime-js\"]\n },\n \"packagers\": {\n \"*.js\": \"@unofficial-parcel-nightly/parcel-packager-js\",\n \"*.css\": \"@unofficial-parcel-nightly/parcel-packager-css\",\n \"*.html\": \"@unofficial-parcel-nightly/parcel-packager-html\",\n \"*.wasm\": \"@parcel/packager-wasm\",\n \"*.raw\": \"@unofficial-parcel-nightly/parcel-packager-raw\"\n },\n \"optimizers\": {\n \"*.js\": [\"@parcel/optimizer-uglify\"],\n \"*.css\": [\"@unofficial-parcel-nightly/parcel-optimizer-cssnano\"],\n \"*.html\": [\"@unofficial-parcel-nightly/parcel-optimizer-htmlnano\"],\n \"*.{png,jpg,jpeg,svg,...}\": [\"@parcel/optimizer-imagemin\"]\n },\n \"reporters\": [\"@unofficial-parcel-nightly/parcel-reporter-cli\"]\n}\n```\n\n#### Glob maps in `.parcelrc`\n\nMany config properties like `transforms` or `packagers` use objects as maps of\nglobs to package names. While objects in JSON are technically unordered, Parcel\ndoes use the order to give globs priority when a file name is being tested\nagainst them.\n\n```json\n{\n \"transforms\": {\n \"icons/*.svg\": [\"highest-priority\"],\n \"*.svg\": [\"lowest-priority\"]\n }\n}\n```\n\nHere if we are trying to find a transform for the file `icons/home.svg`, we'll\nwork our way down the globs until we find a match, which would be\n`icons/*.svg`, we never reach `*.svg`.\n\n#### `.parcelrc#extends`\n\n`extends` can either be a string or an array of strings that specify base\nconfigs to extend. That base configuration can be the path to another\n`.parcelrc` file or the name of a Parcel config package.\n\n```json\n{\n \"extends\": \"@unofficial-parcel-nightly/parcel-config-default\",\n \"extends\": \"../.parcelrc\",\n \"extends\": [\"@unofficial-parcel-nightly/parcel-config-default\", \"@company/parcel-config\"]\n}\n```\n\nWhen extending a config, Parcel does a shallow merge of the two configs.\n\n#### `.parcelrc#resolvers`\n\n`resolvers` is an array of strings that specifies the name of a Parcel resolver\npackage.\n\n```json\n{\n \"resolvers\": [\"@unofficial-parcel-nightly/parcel-resolver-default\"]\n}\n```\n\nSee [Resolvers](#resolvers)\n\n#### `.parcelrc#transforms`\n\n`transforms` is an object map of globs to arrays of Parcel transform packages.\n\n```json\n{\n \"transforms\": {\n \"*.js\": [\"@unofficial-parcel-nightly/parcel-transformer-babel\"]\n }\n}\n```\n\nSee [Transforms](#transforms)\n\n#### `.parcelrc#bundler`\n\n`bundler` is a string that specifies the name of a Parcel bundler package.\n\n```json\n{\n \"bundler\": \"@unofficial-parcel-nightly/parcel-bundler-default\"\n}\n```\n\nSee [Bundlers](#bundlers)\n\n#### `.parcelrc#namers`\n\n`bundler` is an array of Parcel namer packages.\n\n```json\n{\n \"namers\": [\"@unofficial-parcel-nightly/parcel-namer-default\"]\n}\n```\n\nSee [Namers](#namers)\n\n#### `.parcelrc#runtimes`\n\n`runtimes` is an object map of environments to arrays of Parcel runtime packages.\n\n```json\n{\n \"runtimes\": {\n \"browser\": [\"@unofficial-parcel-nightly/parcel-runtime-js\", \"@unofficial-parcel-nightly/parcel-runtime-browser-hmr\"],\n \"node\": [\"@unofficial-parcel-nightly/parcel-runtime-js\"]\n }\n}\n```\n\nSee [Runtimes](#runtimes)\n\n#### `.parcelrc#packagers`\n\n`packagers` is an object map of globs to Parcel packager packages.\n\n```json\n{\n \"packagers\": {\n \"*.js\": [\"@unofficial-parcel-nightly/parcel-packager-js\"]\n }\n}\n```\n\nSee [Packagers](#packagers)\n\n#### `.parcelrc#optimizers`\n\n`optimizers` is an object map of globs to arrays of Parcel optimizer packages.\n\n```json\n{\n \"optimizers\": {\n \"*.js\": [\"@parcel/optimizer-uglify\"]\n }\n}\n```\n\nSee [Optimizers](#optimizers)\n\n#### `.parcelrc#reporters`\n\n`reporters` is an array of Parcel reporter packages.\n\n```json\n{\n \"reporters\": [\"@parcel/reporter-detailed\"]\n}\n```\n\nSee [Reporters](#reporters).\n\n#### `.parcelrc#validators`\n\n`validators` is an object map of globs to arrays of Parcel validator packages.\n\n```json\n\n \"validators\": {\n \"*.ts\": [\"@unofficial-parcel-nightly/validator-typescript\"]\n }\n}\n```\n\nSee [Reporters](#validators).\n\n## Parcel Architecture\n\nEven if you aren't doing anything that complex, if you are going to use Parcel\na lot it makes sense to take some time and understand how it works.\n\n### Phases of Parcel\n\nAt a high level Parcel runs through several phases:\n\n- Resolving\n- Transforming\n- Bundling\n- Packaging\n- Optimizing\n- (Validating)\n\nThe **resolving** and **transforming** phases work together in parallel to\nbuild a graph of all your assets.\n\nThis asset graph gets translated into bundles in the **bundling** phase.\n\nThen the **packaging** phase takes the assets in the calculated bundles and\nmerges them together into files each containing an entire bundle.\n\nFinally, in the **optimizing** phase, Parcel takes these bundles files and runs\nthem through optimizing transforms.\n\n### Asset Graph\n\nDuring the resolving and transforming phases, Parcel discovers all the assets\nin your app or program. Every asset can have it's own dependencies on other\nassets which Parcel will pull in.\n\nThe data structure that represents all of these assets and their dependencies\non one another is known as \"The Asset Graph\".\n\n| Asset Name | Dependencies |\n| ------------ | ------------------- |\n| `index.html` | `app.css`, `app.js` |\n| `app.css` | N/A |\n| `app.js` | `navbar.js` |\n| `navbar.js` | etc. |\n\n### Bundles\n\nOnce Parcel has built the entire Asset Graph, it begins turning it into\n\"bundles\". These bundles are groupings of assets that get placed together in a\nsingle file.\n\nBundles will (generally) contain only assets in the same language:\n\n| Bundle Name | Assets |\n| ------------ | --------------------------- |\n| `index.html` | `index.html` |\n| `app.css` | `app.css` |\n| `app.js` | `app.js`, `navbar.js`, etc. |\n\nSome assets are considered \"entry\" points into your app, and will stay as\nseparate bundles. For example, if your `index.html` file links to an\n`about.html` file, they won't be merged together.\n\n| Bundle Name | Assets | Entry URL |\n| ------------ | ------------ | --------- |\n| `index.html` | `index.html` | `/` |\n| `about.html` | `about.html` | `/about` |\n\n### Sources\n\n\"Sources\" are the files that contain the source code to your app before being\ncompiled by Parcel.\n\nParcel discovers these sources by following their dependencies on one another\nstarting at your \"entries\".\n\nThese entries will be one of:\n\n1. `$ parcel <...entries>`\n2. `~/package.json#source`\n3. `./src/index.*`\n4. `./index.*`\n\nFrom there, everything those assets depend on will be considered a \"source\" in\nParcel.\n\n### Targets\n\nWhen Parcel runs, it can build your asset graph in multiple different ways\nsimultaneously. These are called \"targets\".\n\nFor example, you could have a \"modern\" target that _targets_ newer browsers\nand a \"legacy\" target for older browsers.\n\nSources get mapped to targets,\n\n#### Target Configuration\n\nIn the most explicit form, targets are configured via the\n`package.json#targets` field.\n\n```js\n{\n \"app\": \"dist/browser/index.js\",\n \"appModern\": \"dist/browserModern/index.js\",\n \"targets\": {\n \"app\": { /* target env */ },\n \"appModern\": { /* target env */ }\n }\n}\n```\n\nEach target has a name which corresponds to a top-level `package.json` field\nsuch as `package.json#main` or `package.json#browser` which specify the primary\nentry point for that target.\n\nInside each of those targets contains the target's environment configuration:\n\n| Option | Possible values | Description |\n| -------------------- | --------------- | ----------- |\n| `context` | `'node' \\| 'browser' \\| 'web-worker' \\| 'electron-main' \\| 'electron-renderer'` | Where the bundle should run |\n| `includeNodeModules` | `boolean \\| [String]` | Whether to bundle all/none/some `node_module` dependency |\n| `outputFormat` | `'global' \\| 'esmodule' \\| 'commonjs'` | Which type of imports/exports should be emitted|\n| `publicUrl` | `string` | The public url of the bundle at runtime |\n| `isLibrary` | `boolean` | Library as in 'npm library' |\n| `sourceMap` | `boolean \\| {inlineSources?: boolean, sourceRoot?: string, inline?: boolean}` | Enable/disable sourcemap and set options\n| `engines` | Engines | Same as `package.json#engines` |\n\n\nHowever, a lot of the normal configuration you might want will already have\ndefaults provided for you:\n\n```cs\ntargets = {\n main: {\n engines: {\n node: value(\"package.json#engines.node\"),\n browsers: unless exists(\"package.json#browser\") then value(\"package.json#browserlist\")\n },\n isLibrary: true\n },\n module: {\n engines: {\n node: value(\"package.json#engines.node\"),\n browsers: unless exists(\"package.json#browser\") then value(\"package.json#browserlist\")\n },\n isLibrary: true\n },\n browser: {\n engines: {\n browsers: value(\"package.json#browserslist\")\n },\n isLibrary: true\n },\n ...value(\"package.json#targets\"),\n}\n```\n\n### Environments\n\nEnvironments tell Parcel how to transform and bundle each asset. They tell\nParcel if an asset is going to be run in a browser or in NodeJS/Electron.\n\nThey also tell Parcel's transform plugins how they should run. They tell\n[Babel](http://babeljs.io/docs/en/babel-preset-env#targetsbrowsers) or\n[Autoprefixer](https://github.com/postcss/autoprefixer#browsers) what browsers\nyour asset is targetting.\n\nYou can configure environments through your targets.\n\n```json\n{\n \"targets\": {\n \"main\": {\n \"engines\": {\n \"node\": \">=4.x\",\n \"electron\": \">=2.x\",\n \"browsers\": [\"> 1%\", \"not dead\"]\n }\n }\n }\n}\n```\n\nWhen one asset depends on another, the environment is inherited from its\nparent. But how you depend on the asset can change some properties of that\nenvironment.\n\nFor example:\n\n```js\nnavigator.serviceWorker.register('./service-worker.js');\n```\n\n```js\nlet childEnvironment = {...parentEnvironment, browserContext: 'service-worker'};\n```\n\n### Caching\n\nParcel will create a `/node_modules/.cache/parcel` directory\n\nThe top-level directory will be filled with directories with two letters, which\nare the start of a hash which is finished by the names of the JSON files inside.\n\n```\n/node_modules/.cache/parcel/\n /00/\n 213debd8ddd45819b79a3a974ed487.json\n 40ae9b581afc53841307a4b3c2463d.json\n 63a9dd58fc1e8f8bb819759ea9793c.json\n ...\n /01/\n /../\n /zy/\n /zz/\n```\n\nIt follows this weird structure in order to avoid too many files being created\nin a single directory which degrades file system performance.\n\n## Asset Resolution\n\nParcel follows the Node module resolution algorithm with a few additions.\n\n### Local Paths\n\n```\n./path/to/file\n./path/to/file.js\n```\n\nThese follow the [Node module resolution algorithm](https://nodejs.org/api/modules.html#modules_all_together).\n\n### Package Paths\n\n```\npreact\nlodash/cloneDeep\n@sindresorhus/is\n```\n\nThese follow the [Node module resolution algorithm](https://nodejs.org/api/modules.html#modules_all_together).\n\n### URLs\n\n```\nhttps://unpkg.com/preact@8.2.9/dist/preact.min.js\n```\n\nParcel by default will ignore URL dependencies, other resolver plugins may\nchoose to do something with them.\n\n### Tilde Paths\n\n```\n~/src/file.js\n```\n\nOnly when used outside of `node_modules` directories, the `~` is replaced by an\nabsolute path to the closest package root:\n\n```sh\n/path/to/app #(/package.json)\n```\n\nTo form a path that looks like:\n\n```\n/path/to/app/src/file.js\n```\n\nThen it follows the [Node module resolution algorithm](https://nodejs.org/api/modules.html#modules_all_together).\n\n### Aliases\n\nAliases come in two forms:\n\n1. Package Aliases: `react -> preact`\n2. File/Directory Aliases: `utils` -> `./src/utils`\n\n```json\n{\n \"name\": \"my-project\",\n \"alias\": {\n \"react\": \"preact-compat\",\n \"react-dom\": \"preact-compat\",\n \"utils\": \"./src/utils\",\n \"components\": \"./src/components\"\n }\n}\n```\n\nThere are a couple of rules:\n\n1. Aliases will only be respected when specified outside of `node_modules`.\n2. Aliases specified outside of `node_modules` will affect assets inside of `node_modules`.\n3. Aliases cannot build off of other aliases.\n4. Only one alias will be applied at a time.\n5. Aliases must be valid npm package names.\n\n## Plugins\n\n### Resolvers\n\nWhen one asset depends on another through an asset specifier, the resolver is\nresponsible for determining what asset is being requested.\n\nSee [Asset Resolution](#asset-resolution) for more details.\n\n```json\n{\n \"resolvers\": [\"@parcel/resolver-v1\"]\n}\n```\n\n**Official Resolvers:**\n\n- `@parcel/resolver-v1`\n\n### Transforms\n\nTransforms _transform_ single assets as they are discovered and added to the\nasset graph. They mostly call out to different compilers and preprocessors.\n\n```json\n{\n \"transforms\": {\n \"*.js\": [\"@unofficial-parcel-nightly/parcel-transformer-babel\"]\n }\n}\n```\n\n**Official Transforms:**\n\n- `@parcel/transformer-babel`\n- `@parcel/transformer-coffeescript`\n- `@parcel/transformer-graphql`\n- `@parcel/transformer-json`\n- `@parcel/transformer-json5`\n- `@parcel/transformer-less`\n- `@parcel/transformer-posthtml`\n- `@parcel/transformer-postcss`\n- `@parcel/transformer-pug`\n- `@parcel/transformer-raw`\n- `@parcel/transformer-reason`\n- `@parcel/transformer-rust`\n- `@parcel/transformer-stylus`\n- `@parcel/transformer-toml`\n- `@parcel/transformer-typescript`\n- `@parcel/transformer-vue`\n- `@parcel/transformer-wasm`\n- `@parcel/transformer-webmanifest`\n- `@parcel/transformer-yaml`\n- ...\n\n### Bundlers\n\nBundlers accept the entire asset graph and turn it into sets of bundles.\n\n```json\n{\n \"bundler\": \"@unofficial-parcel-nightly/parcel-bundler-default\"\n}\n```\n\n**Official Bundlers:**\n\n- `@parcel/bundler-default`\n\n### Namers\n\nNamers accept a bundle and return a filename for that bundle.\n\n```json\n{\n \"namers\": [\"@unofficial-parcel-nightly/parcel-namer-default\"]\n}\n```\n\n**Official Namers:**\n\n- `@parcel/namer-default`\n\n### Runtimes\n\nRuntimes get called after the bundler phase and generate an asset which gets\nincluded in the final bundle.\n\n```json\n{\n \"runtimes\": {\n \"browser\": [\"@unofficial-parcel-nightly/parcel-runtime-js\", \"@unofficial-parcel-nightly/parcel-runtime-browser-hmr\"],\n \"node\": [\"@unofficial-parcel-nightly/parcel-runtime-js\"]\n }\n}\n```\n\n**Official Runtimes:**\n\n- `@parcel/runtime-js`\n- `@parcel/runtime-hmr`\n\n### Packagers\n\nPackagers determine how to merge different asset types into a single bundle.\n\n```json\n{\n \"packagers\": {\n \"*.css\": \"@unofficial-parcel-nightly/parcel-packager-css\"\n }\n}\n```\n\n**Official Packagers:**\n\n- `@parcel/packager-html`\n- `@parcel/packager-js`\n- `@parcel/packager-css`\n- `@parcel/packager-wasm`\n- `@parcel/packager-raw`\n\n### Optimizers\n\nOptimizers are similar to transformers, but they accept a bundle instead\nof a single asset.\n\n```json\n{\n \"optimizers\": {\n \"*.js\": [\"@unofficial-parcel-nightly/parcel-optimizer-terser\"],\n \"*.css\": [\"@parcel/optimizer-csso\"]\n }\n}\n```\n\n**Official Optimizers:**\n\n- `@parcel/packager-terser`\n- `@parcel/packager-csso`\n- [todo]\n\n### Reporters\n\nReporters receive events as they happen and can either use the Parcel logger to\noutput to stdout/stderr or they can return assets to be generated on the file\nsystem.\n\n```json\n{\n \"reporters\": [\"@unofficial-parcel-nightly/parcel-reporter-cli\", \"@unofficial-parcel-nightly/parcel-reporter-dev-server\"]\n}\n```\n\n**Official Reporters:**\n\n- `@parcel/reporter-cli`\n- `@parcel/reporter-dev-server`\n- [todo]\n\n### Validators\n\nValidators emit errors for source code after a build is completed.\nFor example, type checking and linting.\n\n```json\n{\n \"validators\": {\n \"*.ts\": [\"@unofficial-parcel-nightly/validator-typescript\"]\n }\n}\n```\n\n**Official Validators:**\n\n- `@parcel/validator-typescript`\n- `@parcel/validator-eslint`\n- [todo]\n\n## Creating Plugins\n\n### Naming\n\nAll plugins must follow a naming system:\n\n| | Official package | Community packages | Private company/scoped team packages |\n| ---------- | -------------------------- | ------------------------- | ------------------------------------ |\n| Configs | `@parcel/config-{name}` | `parcel-config-{name}` | `@scope/parcel-config[-{name}]` |\n| Resolvers | `@parcel/resolver-{name}` | `parcel-resolver-{name}` | `@scope/parcel-resolver[-{name}]` |\n| Transforms | `@parcel/transformer-{name}` | `parcel-transformer-{name}` | `@scope/parcel-transformer[-{name}]` |\n| Bundlers | `@parcel/bundler-{name}` | `parcel-bundler-{name}` | `@scope/parcel-bundler[-{name}]` |\n| Namers | `@parcel/namer-{name}` | `parcel-namer-{name}` | `@scope/parcel-namer[-{name}]` |\n| Runtimes | `@parcel/runtime-{name}` | `parcel-runtime-{name}` | `@scope/parcel-runtime[-{name}]` |\n| Packagers | `@parcel/packager-{name}` | `parcel-packager-{name}` | `@scope/parcel-packager[-{name}]` |\n| Optimizers | `@parcel/optimizer-{name}` | `parcel-optimizer-{name}` | `@scope/parcel-optimizer[-{name}]` |\n| Reporters | `@parcel/reporter-{name}` | `parcel-reporter-{name}` | `@scope/parcel-reporter[-{name}]` |\n| Validators | `@parcel/validator-{name}` | `parcel-validator-{name}`| `@scope/parcel-validator[-{name}]` |\n\nThe `{name}` must be descriptive and directly related to the purpose of the\npackage. Someone should be able to have an idea of what the package does simply\nby reading the name in a `.parcelrc` or `package.json#devDependencies`.\n\n```\nparcel-transformer-posthtml\nparcel-packager-wasm\nparcel-reporter-graph-visualizer\n```\n\nIf your plugin adds support for a specific tool, please use the name of the\ntool.\n\n```\nparcel-transformer-es6 (bad)\nparcel-transformer-babel (good)\n```\n\nIf your plugin is a reimplementation of something that exists, try naming it\nsomething that explains why it is a separate:\n\n```\nparcel-transformer-better-typescript (bad)\nparcel-transformer-typescript-server (good)\n```\n\nWe ask that community members work together and when forks happen to try and\nresolve them. If someone made a better version of your plugin, please consider\ngiving the better package name over, have them make a major version bump, and\nredirect people to the new tool.\n\n### Versioning\n\nYou must follow semantic versioning (to the best of your ability). No, it's not\nthe perfect system, but it's the best one we have and people do depend on it.\n\nIf plugin authors intentionally don't follow semantic versioning, Parcel may\nstart warning users that they should be locking down the version number for\nyour plugin.\n\n> Warning: The plugin \"parcel-transform-typescript\" does not follow semantic\n> versioning. You should lock the version range down so your code does not\n> break when they make changes. Please upvote this issue to encourage them to\n> follow semver: https://github.com/user/parcel-transform-typescript/issues/43\n\n### Engines\n\nYou must specify a `package.json#engines.parcel` field with the version range\nof Parcel that your plugin supports:\n\n```json\n{\n \"name\": \"parcel-transform-imagemin\",\n \"engines\": {\n \"@unofficial-parcel-nightly/parcel\": \"2.x\"\n }\n}\n```\n\nIf you do not specify this field, Parcel will output a warning:\n\n```\nWarning: The plugin \"parcel-transform-typescript\" needs to specify a `package.json#engines.parcel` field with the supported Parcel version range.\n```\n\nIf you do specify the parcel engine field and the user is using an incompatible\nversion of Parcel, they will see an error:\n\n```\nError: The plugin \"parcel-transform-typescript\" is not compatible with the\ncurrent version of Parcel. Requires \"2.x\" but the current version is \"3.1.4\"\n```\n\nParcel uses node-semver to match version ranges.\n\n## Plugin APIs\n\nThere are several different types of plugins. They all look very similar, but\nare kept separate so we can have strict contracts one what each one is allowed\nto do.\n\nThere are some rules that should be followed across every type of plugin:\n\n- **Stateless** — Avoid any kind of state, it will likely be the source of bugs\n for your users. For example, the same transform may exist in multiple\n separate workers which are not allowed to communicate with one another, state\n will not work as expected.\n- **Pure** — Given the same input, a plugin must produce the same output, and\n you must not have any observable side effects, or implicit dependencies.\n Otherwise Parcel's caching will break and your users will be sad. You should\n never have to tell users to delete their caches.\n\nThe plugin APIs all follow a common shape:\n\n```js\nimport {NameOfPluginType} from '@unofficial-parcel-nightly/plugin';\n\nexport default new NameOfPluginType({\n async methodName(opts: JSONObject): Promise {\n return result;\n }\n});\n```\n\nThey are made up of modules with well-known named exports of async functions\nthat:\n\n- Accept a strictly validated JSON-serializable `opts` object.\n- Return a strictly validated JSON-serializable `vals` object.\n\nIf something you need is not being passed through `opts`, please come talk to\nthe Parcel team about it. Avoid trying to get information yourself from other\nsources, especially from the file system.\n\n### Resolvers\n\nResolvers get called with an asset request (consisting of a source file path\nand the specifier of what is being requested) which it then attempts to\nresolve. If the resolver isn't sure how to handle a request, it can also return\n`null` and pass it to the next resolver in the chain.\n\n```js\nimport {Resolver} from '@unofficial-parcel-nightly/plugin';\n\nexport default new Resolver({\n async resolve({dependency}) {\n // ...\n return {filePath} || null;\n }\n});\n```\n\n### Transforms\n\nTransforms _transform_ single assets as they are discovered and added to the\nasset graph. They mostly call out to different compilers and preprocessors.\n\n```js\nimport {Transform} from '@unofficial-parcel-nightly/plugin';\n\nexport default new Transform({\n async getConfig({asset}) {\n // ...\n return config;\n },\n\n async parse({asset}) {\n // ...\n return ast;\n },\n\n async transform({asset}) {\n // ...\n return [assets];\n },\n\n async generate({asset}) {\n // ...\n return {code, map};\n }\n});\n```\n\n### Bundler\n\nBundlers accept the entire asset graph and modify it to add bundle nodes that group the assets\ninto output bundles.\n\n```js\nimport {Bundler} from '@unofficial-parcel-nightly/plugin';\n\nexport default new Bundler({\n async bundle({graph}) {\n // ...\n },\n\n async optimize({graph}) {\n // ...\n }\n});\n```\n\n### Namers\n\nNamers accept a bundle and output a filename for that bundle.\n\n```js\nimport {Namer} from '@unofficial-parcel-nightly/plugin';\n\nexport default new Namer({\n async name({bundle, bundleGraph}) {\n // ...\n return name;\n }\n});\n```\n\n### Runtimes\n\nRuntimes accept a bundle and return assets to be inserted into that bundle.\n\n```js\nimport {Runtime} from '@parcel/runtime';\n\nexport default new Runtime({\n async apply({bundle, bundleGraph}) {\n // ...\n return assets;\n }\n});\n```\n\n### Packagers\n\nPackagers determine how to merge different asset types into a single bundle.\n\n```js\nimport {Packager} from '@unofficial-parcel-nightly/plugin';\n\nexport default new Packager({\n async package({bundle}) {\n // ...\n return {contents, map};\n },\n});\n```\n\n### Optimizers\n\nOptimizers are similar to transformers, but they accept a bundle instead\nof a single asset.\n\n```js\nimport {Optimizer} from '@unofficial-parcel-nightly/plugin';\n\nexport default new Optimizer({\n async optimize({bundle, contents, map}) {\n // ...\n return {contents, map};\n }\n});\n```\n\n### Reporters\n\nReporters receive events as they happen and can output to stdout/stderr,\nor perform other actions.\n\n```js\nimport {Reporter} from '@unofficial-parcel-nightly/plugin';\n\nexport default new Reporter({\n async report({ event: { type, ... } }) {\n // ...\n }\n});\n```\n\n### Validators\n\nValidators receive an asset, and can throw errors if that asset is invalid\nin some way, e.g. type errors or linting errors.\n\n```js\nimport {Validator} from '@unofficial-parcel-nightly/plugin';\n\nexport default new Validator({\n async validate({asset}) {\n // ...\n throw error;\n }\n});\n```\n","readmeFilename":"README.md"}
![\"Parcel\"](\"https://user-images.githubusercontent.com/19409/31321658-f6aed0f2-ac3d-11e7-8100-1587e676e0ec.png\")