Parcel User Guide

Parcel is a zero configuration build tool for the web. Point it at an HTML file (or any entry point) and it bundles your JavaScript, TypeScript, CSS, images, and dozens of other asset types into an optimized application — with a built-in dev server, hot reloading, and automatic production optimization. No config file required to get started.

This guide is for developers using Parcel to build websites, web apps, and libraries. It covers installation, every command-line option, everyday workflows, and troubleshooting. For architecture, plugin authoring, deployment, and internals, see the Admin Guide.

Note

This guide documents Parcel v2.16.4. Parcel requires Node.js 16 or newer. The package is published to npm as parcel.

Table of Contents

1. Quick Start
2. Installation
3. The parcel Command
4. Everyday Usage
5. Common Tasks & Recipes
6. The Development Server & Hot Reloading
7. Building for Production
8. Working with Different File Types
9. Programmatic API
10. How Parcel Works (Concepts)
11. Troubleshooting
12. Frequently Asked Questions
13. Command & Option Reference

1. Quick Start

Get a project running in under a minute. Parcel needs an entry point — usually an HTML file that references your scripts and styles.

1. Create a project and install Parcel:

mkdir my-app && cd my-app
npm install --save-dev parcel

2. Create an entry HTML file (src/index.html) that references a script:

<!DOCTYPE html>
<html>
  <head>
    <title>My App</title>
  </head>
  <body>
    <h1>Hello Parcel</h1>
    <script type="module" src="./app.js"></script>
  </body>
</html>

3. Create the script (src/app.js):

console.log('Bundled by Parcel!');

4. Start the development server:

npx parcel src/index.html

Server running at http://localhost:1234
✨ Built in 120ms

Open http://localhost:1234 in your browser. Edit app.js or index.html and the page reloads automatically.

5. Build for production when you're ready to ship:

npx parcel build src/index.html

Your optimized output lands in the dist/ directory.

Tip

You did not write a single line of configuration. Parcel detected the HTML entry, found the linked script, compiled it, started a server, and enabled hot reloading — all by default. Configuration only becomes necessary when you outgrow the defaults.

2. Installation

Requirements

Install into a project

Install Parcel as a development dependency. This is the recommended approach because it pins Parcel's version to your project.

npm

npm install --save-dev parcel

Yarn

yarn add --dev parcel

pnpm

pnpm add --save-dev parcel

Run it

Once installed, run Parcel through your package manager's runner or via an npm script:

npx parcel src/index.html

A typical package.json wires Parcel into named scripts:

{
  "scripts": {
    "start": "parcel src/index.html",
    "build": "parcel build src/index.html"
  }
}

npm start      # development server
npm run build  # production build

Important

Prefer a local (project) install over a global install. A local install guarantees every contributor and CI run uses the exact same Parcel version recorded in your lockfile.

Scaffolding a new project

Parcel ships an official scaffolding tool (create-parcel) that generates a starter project with the standard start/build scripts already configured.

Note

If you are starting from scratch, scaffolding a project gives you a sensible directory layout and pre-wired scripts. If you are adding Parcel to an existing project, the manual install above is the right path.

3. The parcel Command

Parcel exposes a single binary, parcel, with four subcommands.

The default command

Running parcel with no recognized subcommand is the same as running parcel serve. Parcel inspects the first argument; if it is not one of serve, watch, build, or help, Parcel inserts serve automatically.

parcel src/index.html
# is equivalent to
parcel serve src/index.html

Entry points

Every command accepts one or more entry points ([input...]) — files or globs that Parcel should treat as the roots of your application. If you provide none, Parcel uses the current directory (.).

parcel build src/index.html                  # single entry
parcel build src/index.html src/admin.html   # multiple entries
parcel build "src/*.html"                     # glob (quote it so your shell doesn't expand it)

Tip

Quote glob patterns ("src/*.html"). Without quotes your shell expands the glob before Parcel sees it, which produces inconsistent results across shells and operating systems.

Getting help

parcel help          # general help
parcel help build    # options for the build command
parcel --help        # same as `parcel help`
parcel --version     # print the Parcel version

4. Everyday Usage

This section walks through the tasks you'll perform daily, grouped by what you're trying to accomplish.

Start developing

parcel src/index.html

Server running at http://localhost:1234
✨ Built in 340ms

Parcel serves your app at http://localhost:1234, watches every file in the dependency graph, and reloads the browser (or hot-swaps modules) when you save.

Pick a different port

The dev server listens on port 1234 by default, or the value of the $PORT environment variable.

parcel src/index.html --port 8080

If the requested port is already in use and you did not specify one explicitly, Parcel automatically picks the next free port and warns you. If you did specify a port that's taken, Parcel fails with an error so the behavior is predictable.

Open the browser automatically

parcel src/index.html --open
parcel src/index.html --open firefox   # open a specific browser

Serve over HTTPS

parcel src/index.html --https                       # auto-generated certificate
parcel src/index.html --https --cert cert.pem --key key.pem   # your own certificate

Rebuild without serving

Use watch when another server (e.g. an Express or Rails backend) serves your files and you only need Parcel to keep the bundles fresh:

parcel watch src/index.html

watch produces the same output as a build but keeps running and rebuilds incrementally on change. Unlike build, it does not minify by default (it runs in development mode).

Build for production

parcel build src/index.html

build runs in production mode: minification, scope hoisting, content hashing, and tree shaking are all enabled automatically. Output is written to dist/.

Change the output directory

parcel build src/index.html --dist-dir build

The default output directory is dist/.

Stop a running server

Press Ctrl+C. Parcel writes its asset graph to the cache before exiting so the next start is fast.

Note

While serve or watch is running in an interactive terminal, Parcel listens for these keyboard shortcuts:

Keys	Action
Ctrl+C	Gracefully exit (flushes the cache first)
Ctrl+E	Start/stop sampling build profiling
Ctrl+Y	Take a heap snapshot

5. Common Tasks & Recipes

Build multiple targets at once

If your project defines multiple build targets (for example a modern and a legacy bundle), build a specific one with --target:

parcel build --target modern
parcel build --target modern --target legacy   # repeat the flag for several

Set a public URL / path prefix

When your app is served from a subpath (e.g. https://example.com/app/), tell Parcel the prefix so absolute URLs resolve correctly:

parcel build src/index.html --public-url /app/

The default public URL is /.

Disable minification for a readable production build

parcel build src/index.html --no-optimize

Disable scope hoisting

Scope hoisting concatenates modules for smaller, faster output. Disable it for easier-to-debug bundles:

parcel build src/index.html --no-scope-hoist

Turn off source maps

Source maps are generated by default in both development and production. Disable them with:

parcel build src/index.html --no-source-maps

Build async bundles lazily (faster dev startup)

In large apps, --lazy defers building async (dynamically imported) bundles until the browser actually requests them. This dramatically speeds up the initial dev server start.

parcel serve src/index.html --lazy
parcel serve src/index.html --lazy "pages/**"          # only lazily build matching entries
parcel serve src/index.html --lazy --lazy-exclude "admin/**"   # exclude some from lazy mode

Warning

--lazy-exclude can only be used together with --lazy. Lazy bundling is a development-server feature — it is not compatible with content hashing (see Troubleshooting).

Get a detailed build report

parcel build src/index.html --detailed-report          # top 10 assets per bundle
parcel build src/index.html --detailed-report 25        # top 25

This prints per-asset timings and sizes so you can find what's bloating your bundles.

Profile a slow build

parcel build src/index.html --profile   # sampling CPU profile
parcel build src/index.html --trace      # detailed build trace (uses the tracer reporter)

Use a custom config or cache location

parcel build src/index.html --config ./my-parcelrc.json
parcel build src/index.html --cache-dir .cache

Disable the cache (force a clean build)

parcel build src/index.html --no-cache

Caution

Disabling the cache makes every build start from scratch and is significantly slower. Use it only when you suspect a stale-cache bug — not as a routine flag.

Quiet or verbose output

parcel build src/index.html --log-level error     # only errors
parcel build src/index.html --log-level verbose    # everything

Valid levels: none, error, warn, info, verbose.

6. The Development Server & Hot Reloading

What you get for free

When you run parcel serve (or just parcel), Parcel:

• Serves your app at http://localhost:1234
• Watches every file in the dependency graph
• Hot Module Replacement (HMR) — swaps changed modules in the running page without a full reload where possible
• Shows a built-in error overlay in the browser when a build fails
• Falls back to a full page reload when a module can't be hot-swapped

Hot reloading options

parcel serve src/index.html --no-hmr          # plain reload, no HMR
parcel serve src/index.html --hmr-port 12345

Host, CORS, and stdin

parcel serve src/index.html --host 0.0.0.0     # listen on all interfaces (default behavior)
parcel serve src/index.html --no-cors           # disable CORS headers
parcel serve src/index.html --watch-for-stdin   # exit automatically when stdin closes

Tip

--watch-for-stdin is useful when Parcel is launched as a child process by another tool — the server shuts down cleanly when the parent process closes the pipe.

Choosing a file-watcher backend

Parcel watches the filesystem to know when to rebuild. The available backends depend on your OS:

parcel serve src/index.html --watch-backend watchman

By default Parcel picks the best native backend for your platform.

parcel serve src/index.html --watch-dir /path/to/project    # set the watch root
parcel serve src/index.html --watch-ignore .git,dist        # directories to ignore

The watch root defaults to the nearest lockfile or source-control directory; --watch-ignore defaults to .git and .hg.

Important

On Linux, editing a watched file can stop triggering rebuilds unless Watchman is installed (a known limitation). If hot reloading stops working on Linux, install Watchman or pass --watch-backend watchman.

7. Building for Production

parcel build is tuned for shipping. These optimizations are on by default in build mode:

Note

In build mode, NODE_ENV defaults to production (overridable). In serve/watch mode it defaults to development. This value is exposed to your code and to any JS-based config.

A typical production build

NODE_ENV=production parcel build src/index.html

✨ Built in 4.21s

dist/index.html              1.2 KB    312ms
dist/index.4f8a2c.js        148 KB    1.8s
dist/index.9b1e7d.css        22 KB    140ms

Continuous Integration

In CI, Parcel automatically disables auto-install (it detects the CI environment variable in build mode), so a missing plugin fails the build instead of silently installing packages.

# In CI, install deps first, then build deterministically:
npm ci
npm run build

Tip

Commit your lockfile and run npm ci (not npm install) in CI. Combined with Parcel's content hashing, this gives byte-stable, reproducible production output.

Exit codes

8. Working with Different File Types

Parcel understands a huge range of file types out of the box — no plugins to install for the common cases. It picks the right compiler based on the file extension.

Supported out of the box

Tip

TypeScript and JSX just work — no tsconfig-driven build step or Babel preset required. Import a .ts or .tsx file and Parcel compiles it. Parcel's JavaScript/TypeScript compiler is written in Rust for native speed.

Importing assets

Import any supported asset directly from your JavaScript and Parcel wires up the dependency:

import './styles.css';            // bundled and injected
import logo from './logo.png';    // logo === the output URL of the optimized image
import data from './config.toml'; // parsed to a JS object

Named import pipelines

Parcel supports special URL-scheme prefixes on imports to control how an asset is processed:

import workerUrl from 'url:./worker.js';
import iconDataUrl from 'data-url:./icon.svg';

Code splitting

Use a dynamic import() to create a separate bundle that loads on demand. Parcel does the splitting automatically:

button.addEventListener('click', async () => {
  const { renderChart } = await import('./chart.js'); // becomes its own bundle
  renderChart();
});

Tip

Combine dynamic imports with the dev-server --lazy flag so those split bundles are only built when first requested — keeping cold-start times low in large apps.

9. Programmatic API

Beyond the CLI, Parcel exposes a JavaScript API via the @parcel/core package. Use it to embed Parcel in your own tooling.

A one-shot build

import {Parcel} from '@parcel/core';

const bundler = new Parcel({
  entries: 'src/index.html',
  defaultConfig: '@parcel/config-default',
  mode: 'production',
});

try {
  const {bundleGraph, buildTime} = await bundler.run();
  const bundles = bundleGraph.getBundles();
  console.log(`✨ Built ${bundles.length} bundles in ${buildTime}ms!`);
} catch (err) {
  // Build failures are thrown as a BuildError
  console.error(err.diagnostics);
}

run() resolves with a build-success event (containing the bundle graph, changed assets, and build time) or throws a BuildError whose diagnostics describe what went wrong.

Watch mode

import {Parcel} from '@parcel/core';

const bundler = new Parcel({
  entries: 'src/index.html',
  defaultConfig: '@parcel/config-default',
});

const subscription = await bundler.watch((err, event) => {
  if (err) throw err;
  if (event.type === 'buildSuccess') {
    console.log(`✨ Built ${event.bundleGraph.getBundles().length} bundles`);
  } else if (event.type === 'buildFailure') {
    console.error(event.diagnostics);
  }
});

// later, to stop watching:
await subscription.unsubscribe();

Public exports

The @parcel/core package exports:

Note

new Parcel(options) is cheap — the heavy initialization (loading config, starting the worker farm, opening the cache) happens lazily on the first run() or watch() call.

10. How Parcel Works (Concepts)

You don't need this section to use Parcel, but understanding the model helps you reason about builds.

Zero configuration

Parcel ships a default configuration (@parcel/config-default) that maps every supported file extension to the right compiler. You only create a .parcelrc when you need to add or replace a plugin. (The full plugin pipeline and how to customize it is documented in the Admin Guide.)

The asset pipeline

Every file flows through a series of plugin stages:

Entry → Resolver → Transformers → Bundler → Namer → Runtimes → Packager → Optimizer → Compressor → (write to dist) → Reporter

• Resolvers turn an import specifier into a file path.
• Transformers compile each asset (TypeScript → JS, Sass → CSS, image optimization, …).
• The Bundler groups assets into bundles; Namers give them filenames.
• Packagers combine a bundle's assets into final output; Optimizers minify it.
• Reporters surface progress, the dev server, and the error overlay.

Caching

Parcel caches everything in .parcel-cache. Unchanged code is never rebuilt — even across restarts. This is why the second build of a project is dramatically faster than the first.

Tip

The cache is safe to delete (.parcel-cache/) if you ever suspect corruption. Parcel will simply rebuild from scratch on the next run. Add .parcel-cache and dist to your .gitignore.

Targets and environments

A target describes an output: where it goes (distDir), its public URL prefix, and which environments (browsers/Node versions) it must support. The CLI flags --target, --dist-dir, and --public-url set the default target's options; richer per-target configuration lives in your package.json. See the Admin Guide for the complete target and environment reference.

Parallelism and native speed

Parcel runs transformations in parallel across a worker farm (one worker per CPU core by default) and implements its hottest paths — the JavaScript compiler, the HTML transformer, and the module resolver — in Rust for native performance.

11. Troubleshooting

Each entry lists the cause and the fix. Error messages are quoted exactly as Parcel emits them.

Error: Port "1234" could not be used

Cause: You passed --port with a value that's already in use by another process. Solution: Choose a free port, or omit --port to let Parcel auto-select one.

parcel serve src/index.html --port 4000

Prevention: Don't hard-code a port that other dev servers also use; rely on auto-selection during development.

Error: Lazy bundling does not work with content hashing

Cause: --lazy was combined with content hashing. Lazy-built bundles can't have stable content hashes because they're produced on demand. Solution: Use --lazy only with parcel serve/watch (where content hashing is off by default), or drop --lazy for production builds. Prevention: Treat --lazy as a development-only speed feature.

Error: Initiated Worker with invalid execArgv flags (ERR_WORKER_INVALID_EXEC_ARGV)

Cause: A known incompatibility between Parcel's worker farm and certain newer Node.js releases (reported on Node 24.7.0+). Solution: Use a Node.js LTS release that Parcel supports. If you must run a bleeding-edge Node, clear NODE_OPTIONS of unsupported worker flags before running Parcel. Prevention: Pin your project to a Node LTS version via .nvmrc or engines.

Error: Failed to load native binding / Unsupported architecture on ... ${arch}

Cause: Parcel's prebuilt Rust binary for your OS/CPU architecture was not installed (common on uncommon platforms, in restricted Docker images, or when optionalDependencies were skipped). Solution: Reinstall dependencies without skipping optional ones (npm install — not npm install --no-optional). Ensure your platform/architecture is supported. Prevention: Don't pass --no-optional / --omit=optional when installing; Parcel's native binaries are delivered as optional dependencies.

Dev server stops reloading on Linux after editing a file

Cause: The default watcher backend can miss edits on some Linux setups (reported issue). Solution: Install Watchman and/or pass --watch-backend watchman.

parcel serve src/index.html --watch-backend watchman

Prevention: Install Watchman as part of your Linux dev environment setup.

Error: @parcel/fs tried to access @parcel/core (a peer dependency) but it isn't provided by its ancestors

Cause: Mismatched or partially installed @parcel/* packages — usually from mixing Parcel versions or a corrupted install. Solution: Delete node_modules and your lockfile, then reinstall so every @parcel/* package resolves to the same version.

rm -rf node_modules package-lock.json && npm install

Prevention: Keep all @parcel/* packages on the same version.

Error: Could not get available port

Cause: Parcel could not find any free port to bind the dev server to. Solution: Free up ports, or specify an available one with --port.

Build behaves oddly / picks up stale output

Cause: A corrupted or stale cache. Solution: Build once with --no-cache, or delete .parcel-cache/.

rm -rf .parcel-cache && parcel build src/index.html

Error: Neither npm nor yarn found on system

Cause: Parcel's auto-install needs a package manager on PATH to install a missing plugin and couldn't find one. Solution: Ensure npm or yarn is installed and on your PATH, or pass --no-autoinstall and install the missing package yourself.

Error: PostCSS config should be an object. / PostCSS config must have plugins

Cause: A malformed PostCSS configuration (.postcssrc, postcss.config.js, …). Solution: Ensure the config exports an object with a plugins field. Prevention: Validate your PostCSS config against the PostCSS documentation.

Error: Bundles conflicting names

Cause: Two bundles resolved to the same output filename (reported with service workers in web extensions). Solution: Adjust your entry/target configuration so output names are unique. Check for duplicate entry points producing identically named bundles.

12. Frequently Asked Questions

Q: Do I really need zero configuration? Yes — for most projects you never write a config file. Parcel's default configuration maps every supported extension to the correct compiler. You only add a .parcelrc when you need a plugin that isn't built in. See the Admin Guide for that.

Q: How do I use TypeScript? Just import .ts/.tsx files. Parcel compiles them with its built-in Rust-based compiler. No Babel preset or separate tsc step is needed for bundling. (For emitting .d.ts type declarations of a library, the types: import pipeline and the TypeScript types transformer handle that.)

Q: What's the default dev-server port? 1234, or the value of the $PORT environment variable. Override with --port.

Q: Where does the output go? To dist/ by default. Change it with --dist-dir or per-target configuration in package.json.

Q: How do I make a production build? parcel build <entry>. Minification, scope hoisting, tree shaking, and content hashing are all enabled automatically.

Q: What's the difference between serve and watch? serve runs a development HTTP server with hot reloading. watch rebuilds on change but does not serve — use it when another server hosts your files.

Q: How do I split my code into multiple bundles? Use a dynamic import(). Parcel automatically creates a separate, on-demand bundle for the imported module.

Q: Why is my first build slow but later ones fast? The first build populates the .parcel-cache. Subsequent builds reuse cached results for unchanged files, even across restarts.

Q: Can I run Parcel from my own Node script? Yes — use the @parcel/core programmatic API (new Parcel(options), then run() or watch()). See Programmatic API.

Q: Does Parcel generate source maps? Yes, by default, in both development and production. Disable with --no-source-maps.

Q: How do I target specific browsers? Define a browserslist in your package.json, and/or configure targets there. Parcel transforms your code to match. (Full target/environment reference: Admin Guide.)

Q: How do I add a plugin (e.g. a custom transformer)? Create a .parcelrc that extends the default config and registers your plugin. The plugin system and authoring guide are in the Admin Guide.

Q: How do I speed up the dev server for a huge app? Use --lazy so async bundles are only built when the browser requests them.

Q: How do I see what's making my bundle large? Run parcel build --detailed-report for per-asset sizes and timings.

Q: Is Parcel free? Yes. Parcel is open source under the MIT license.

13. Command & Option Reference

Commands

Options by command

✓ = available on that command.

HMR / dev-server options (serve and watch)

Common options (all of serve, watch, build)

Environment variables

Interactive keys (while serving/watching in a TTY)

Defaults at a glance