Parcel 02 📦 Installation — parcel package & CLI basics - KandZ

⏱️ Estimated read: 11 min | |

Parcel is distributed as a single npm package named parcel, installed as a development dependency. The package includes the CLI and the default configuration, so the installation is one command and the first build works without any additional setup. The previous chapter covered the zero-config philosophy and the asset graph; this chapter covers the installation command and the three CLI commands that drive the build: serve, watch, and build.

Quick How-To Guides & Fast FixesNeed a quick fix or step-by-step solution? Browse our fast answers on HowTo.KandZ.me:

Operating Systems CLI →Dev Environment Languages →Web Network Tools →Security Accounts →Security Access Tech →Device Phone Basics →Social Messaging →Digital Files Media →

The package is installed with npm install --save-dev parcel (or the equivalent for yarn, pnpm, or bun). The --save-dev flag places the package in devDependencies, which is correct because Parcel is a build tool, not a runtime dependency . After the installation, the parcel binary is available in node_modules/.bin, and it can be invoked through npx parcel or through the package.json scripts.

Key point: The parcel command without a subcommand defaults to serve, the development server. The parcel build command performs a single production build and exits. The parcel watch command rebuilds on change but does not start the HTTP server, which is the correct choice for a library or a backend with its own server .

Why the installation requires the CLI understanding

The default-command problem.

The parcel command accepts an entry file as its argument, and the default command is serve. Running npx parcel src/index.html starts the development server with hot reloading. Running npx parcel build src/index.html performs the production build. The two commands produce different outputs: the serve command keeps the process running and serves the files from memory, and the build command writes the optimized assets to the dist/ directory and exits . Confusing the two leads to a production deployment that serves the development output.

The entry problem.

All Parcel commands accept one or more entries: the relative or absolute file paths, the globs, or the directories containing a package.json with the source field. If the entries are omitted, Parcel uses the source field in the current package.json . The HTML file is the conventional entry for a web application, because the asset graph follows the <script>, <link>, and <img> tags from there. A JavaScript entry works for a library, but it misses the CSS and the image dependencies that the HTML would have discovered.

The build-flag problem.

The parcel build command enables the production optimizations by default: the minification, the scope hoisting, and the NODE_ENV=production. The --no-minify and --no-scope-hoist flags disable the specific optimizations when the debugging is needed . The --dist-dir flag sets the output directory, and the --public-url sets the path prefix for the absolute URLs .

a. The installation command

The installation is a single package-manager command, and the package is placed in the devDependencies.

# Install Parcel as a dev dependency
npm install --save-dev parcel

# Or with yarn
yarn add --dev parcel

# Or with pnpm
pnpm add -D parcel

The --save-dev flag records the dependency in the devDependencies section of the package.json . The package includes the CLI and the default config, so no additional packages are required for the basic build.

The package.json scripts are the lifecycle.

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

The dev script runs the serve command through the default parcel invocation, and the build script runs the production build . The parcel command in the script resolves to the local binary in node_modules/.bin, so the global installation is not needed.

b. The serve and watch commands

The serve command starts the development server with the hot module replacement. The watch command rebuilds on change but does not start the HTTP server.

# Start the dev server
npx parcel src/index.html

# Start the dev server on a specific port
npx parcel src/index.html --port 3000

# Watch without the HTTP server
npx parcel watch src/index.html

The serve command is the default, so the parcel src/index.html and the parcel serve src/index.html are equivalent . The --port flag sets the dev server port, and the default is the process.env.PORT or 1234 . The --open flag opens the entry in the browser automatically.

The watch command is for the libraries and the backends. It rebuilds the output on the file changes and supports the HMR, but it does not serve the files over HTTP. The developer uses their own server—the Node.js backend, the Nginx, or the framework’s dev server—and the Parcel only produces the updated assets .

c. The build command and the entries

The build command performs the single production build and exits.

# Production build
npx parcel build src/index.html

# Build with a custom output directory
npx parcel build src/index.html --dist-dir public

# Build multiple entries
npx parcel build src/a.html src/b.html

The build command enables the minification and the scope hoisting by default, and it sets the NODE_ENV=production . The --dist-dir flag overrides the default dist/ output directory . The multiple entries produce one bundle per entry, and the shared dependencies are deduplicated.

The glob entries need the single quotes.

# The glob is quoted so the shell does not expand it
npx parcel build 'src/*.html'

The single quotes prevent the shell from expanding the glob, which allows Parcel to receive the pattern and pick up the newly created files that match it without a restart . The unquoted glob would be expanded by the shell into the list of the current files, and the new files would not be included.

Complete Example Session

# ============================================
# PART 1: CREATE THE PROJECT DIRECTORY
# ============================================
mkdir my-parcel-app && cd my-parcel-app

# ============================================
# PART 2: INSTALL PARCEL
# ============================================
npm install --save-dev parcel

# ============================================
# PART 3: CREATE THE ENTRY HTML
# ============================================
cat > index.html <<'EOF'
<!doctype html>
<html>
  <body>
    <script type="module" src="./src/index.js"></script>
  </body>
</html>
EOF

# ============================================
# PART 4: CREATE THE SOURCE
# ============================================
mkdir src && echo "console.log('hello')" > src/index.js

# ============================================
# PART 5: START THE DEV SERVER
# ============================================
npx parcel index.html
# The server starts on http://localhost:1234

# ============================================
# PART 6: BUILD FOR PRODUCTION
# ============================================
npx parcel build index.html
# The output is in dist/

# ============================================
# PART 7: THE WATCH MODE
# ============================================
npx parcel watch index.html
# The output updates on change, no HTTP server

The seven parts demonstrate the installation and the CLI lifecycle: the project setup, the install, the HTML entry, the source, the dev server, the production build, and the watch mode.

Quick Reference

The Installation

Package Manager	Command
npm	`npm install --save-dev parcel`
yarn	`yarn add --dev parcel`
pnpm	`pnpm add -D parcel`

The CLI Commands

Command	Purpose
`parcel <entry>`	The dev server (default `serve`)
`parcel serve <entry>`	The dev server explicitly
`parcel watch <entry>`	The rebuild on change, no HTTP server
`parcel build <entry>`	The production build, exits

The Common Flags

Flag	Purpose
`--port <port>`	The dev server port (default 1234)
`--dist-dir <dir>`	The output directory (default `dist/`)
`--public-url <url>`	The path prefix for the absolute URLs
`--no-source-maps`	Disable the source maps
`--no-cache`	Disable the filesystem cache
`--open`	Open the entry in the browser

The Entries

Form	Example
Single file	`parcel src/index.html`
Multiple files	`parcel src/a.html src/b.html`
Glob (quoted)	`parcel 'src/*.html'`
Directory with `source`	`parcel packages/frontend`
Current directory `source`	`parcel`

Best Practices

✅ Do This:

# Install as a dev dependency
npm install --save-dev parcel                                 # ✅

# Use the HTML entry for the web apps
npx parcel src/index.html                                     # ✅

# Quote the globs
npx parcel build 'src/*.html'                                 # ✅

# Use the watch mode for the libraries
npx parcel watch src/index.js                                 # ✅

# Set the output directory explicitly when needed
npx parcel build src/index.html --dist-dir public             # ✅

❌ Don’t Do This:

# Install as a production dependency
npm install parcel    # The build tool is not runtime            # ❌

# Use the JavaScript entry for a web app
npx parcel src/index.js    # The CSS and images missed         # ❌

# Leave the glob unquoted
npx parcel build src/*.html    # The shell expands it          # ❌

# Assume the watch command serves HTTP
npx parcel watch    # No HTTP server, only HMR                 # ❌

# Forget the --dist-dir when the target expects a specific output
npx parcel build    # The default is dist/                    # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
The CSS is not bundled	The entry is the JavaScript	Use the HTML entry
The glob misses new files	The shell expanded the glob	Quote the glob
The dev server does not start	The port is in use	Use `--port`
The production build is not optimized	The `serve` command used	Use `parcel build`
The output is in the wrong place	The `--dist-dir` missing	Add the flag or configure the target

Real-World Examples

1. Install Parcel

npm install --save-dev parcel

2. Start the dev server

npx parcel src/index.html

3. Build for production

npx parcel build src/index.html

4. Watch a library

npx parcel watch src/index.js

5. Multiple entries

npx parcel build src/a.html src/b.html

6. The quoted glob

npx parcel build 'src/*.html'

7. The custom port

npx parcel src/index.html --port 3000

8. The custom output

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

9. The package.json script

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

10. The version check

npx parcel --version

Visual

The Three Commands

┌──────────────────────────────────────────────────────────────┐
│  SERVE, WATCH, AND BUILD SERVE DIFFERENT PURPOSES            │
│                                                              │
│  serve (default):                                            │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ The HTTP dev server + the HMR                          │  │
│  │ The output is served from memory                       │  │
│  │ The process stays running                              │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  watch:                                                      │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ The HMR server only, no HTTP server                    │  │
│  │ The output is written to the disk on change            │  │
│  │ For the libraries and the backends                     │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  build:                                                      │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ The single production build, exits                     │  │
│  │ The minification + the scope hoisting                   │  │
│  │ The output is written to dist/                         │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

The Entry Selection

┌──────────────────────────────────────────────────────────────┐
│  THE HTML ENTRY FOLLOWS ALL THE DEPENDENCIES                  │
│                                                              │
│  index.html                                                  │
│  ├── <script src="./src/index.js">                           │
│  ├── <link href="./styles.css">                              │
│  └── <img src="./logo.png">                                  │
│                                                              │
│  The JavaScript entry would only follow the imports in the JS│
│  The HTML entry follows the script, the stylesheet, and the  │
│  image references.                                           │
└──────────────────────────────────────────────────────────────┘

The Glob Quoting

┌──────────────────────────────────────────────────────────────┐
│  THE QUOTED GLOB IS PASSED TO PARCEL, NOT THE SHELL          │
│                                                              │
│  ✅ Quoted:                                                  │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ npx parcel build 'src/*.html'                          │  │
│  │ → Parcel receives the pattern                          │  │
│  │ → The new files are picked up automatically            │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  ❌ Unquoted:                                                │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ npx parcel build src/*.html                            │  │
│  │ → The shell expands the glob into the current files    │  │
│  │ → The new files are not picked up                      │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

Summary

Item	Value
Package	`parcel` (installed as a dev dependency)
Install command	`npm install --save-dev parcel`
Default command	`serve` (the dev server)
Production command	`parcel build`
Watch command	`parcel watch` (no HTTP server)
Default port	`1234` (or `process.env.PORT`)
Default output	`dist/`
Entry	The HTML file for the web apps
Glob	The quoted glob is passed to Parcel

Key takeaways:

Parcel is installed as a single dev dependency. The npm install --save-dev parcel is the installation command, and the package includes the CLI and the default config .
The parcel command defaults to serve. The parcel src/index.html starts the dev server with the HMR. The parcel build src/index.html performs the production build .
The watch command is for the libraries and the backends. It rebuilds on change but does not start the HTTP server, which is the correct choice when the developer has their own server .
The HTML entry follows all the dependencies. The JavaScript entry misses the CSS and the image references. The HTML entry lets the asset graph discover the whole application .
The globs must be quoted. The unquoted glob is expanded by the shell, and the new files are not picked up. The quoted glob is passed to Parcel, which can watch for the new files .
The --port and the --dist-dir flags control the dev server and the output. The default port is 1234, and the default output is dist/. The flags override the defaults when the environment requires it .

Remember: The Parcel installation is one command, and the CLI has three commands: serve, watch, and build. The serve command starts the dev server with the HMR, the watch command rebuilds on change without the HTTP server, and the build command performs the production build. The HTML entry is the conventional choice for the web apps, and the quoted globs are the mechanism that picks up the new files. The result is the zero-config build that works from the first command, which is the promise that Parcel makes and keeps.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!