¶ Installing the Parcel CLI
The Parcel CLI is built into the main
While you can install and run Parcel globally, it is much better to install it locally into your project as a dev dependency. To do this navigate to the project in the terminal and run the install command listed below.
To install Parcel, run the following command:
yarn add -D parcel@next
Or when using NPM run:
npm install -D parcel@next
¶ Setting up the Project
¶ Example Project
To make running parcel easier, you should add some
scripts to your
package.json, these are a kind of shortcut to a usually longer command. Below we're gonna suggest some minimal Parcel commands to get you started.
Common names for these scripts are
start for starting the development environment and
build for building a production version of your application. We will be using these naming conventions in the example below.
To run the development environment in this example you can run
yarn run start or
npm run start.
To create a production build in this example you can run
yarn run build or
npm run build.
¶ Parcel commands explained
In the above example you can see two commands, the development command
parcel serve ./src/index.html and
parcel build ./src/index.html for creating production builds.
Note that the commands in the example have
¶ Development command
The development command
parcel serve ./src/index.html starts up a development server for serving your JS, HTML, CSS files and any other assets of your project.
Besides the hosting of these assets, we also start a Hot Module Reload server which is a websocket that listens to build events and reloads a script, style or your entire page depending on what changed (if you are using React, we even have React Fast Refresh built in). This is super useful as you no longer have to wait for the build to complete and manually refresh the page, although you can still do this if you want by adding the
--no-hmr flag to the command.
It also ensures all used libraries and frameworks are built in development mode, meaning you will get additional debug information if they provide any. Parcel sets the
process.env.NODE_ENV variable to
development, generates source maps and doesn't do any minification.
¶ Production build command
The production build command
parcel build ./src/index.html does exactly what it says it does, which is building your application.
It creates production-ready bundles that contain very little to no unused and development code, ensuring your end-user gets fast load times. We achieve this by telling frameworks and libraries we're building for production by setting the
process.env.NODE_ENV variable to
These bundles are also named in such a way that any non-html assets can be cached safely by a CDN for a very long time without any user ever having an incorrect or outdated bundle as the name includes a hash of the final bundle content.
By default Parcel does not perform any code transpilation. This means that if you write in ES2020 syntax, that's what Parcel will output. You may wish to support older browsers that don't support these syntax features natively, however, which you can do by configuring a browserslist.
¶ How to configure browserslist
To configure a browserslist you can take a couple approaches, you can define it in your
package.json file under the
browserslist key or in a seperate configuration file:
You can find more information over in the Browserslist repo
In our configuration section, we explain how you can set targets for configuring Parcel.
¶ Differential Serving
Parcel also supports differential serving, which means you can serve different bundles to modern browsers and legacy browsers. This results in faster load time for most users as the bundle size will be a lot smaller. Parcel will automatically generate a
<script nomodule> tag when you use a
<script type="module"> in your HTML, and specify a browserslist that includes targets that do not support ES modules natively. This way, modern browsers will download the smaller
type="module" version, and legacy browsers will download the
nomodule version. If all of your browser targets support ES modules natively, or you do not specify a browserslist, then no
nomodule version will be inserted.