CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-parcel

Zero configuration web application bundler with blazing fast performance and comprehensive dev server

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

index.mddocs/

Parcel

Parcel is a blazing fast, zero configuration web application bundler designed for modern web development. Built with performance in mind, it features a JavaScript compiler written in Rust for native performance, parallel processing using worker threads, and comprehensive caching to avoid rebuilding unchanged code.

Package Information

  • Package Name: parcel
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install -g parcel or npm install --save-dev parcel

Core Usage

Parcel is a CLI-only tool that provides zero-configuration bundling through command-line interface:

# Start development server (default command)
parcel index.html

# Build for production
parcel build index.html

# Watch mode without dev server
parcel watch index.html

# Get help
parcel help

Basic Usage

# Install Parcel globally
npm install -g parcel

# Create a simple HTML file
echo '<html><body><script src="./app.js"></script></body></html>' > index.html
echo 'console.log("Hello Parcel!");' > app.js

# Start development server
parcel index.html
# ✨ Built in 123ms
# Server running at http://localhost:1234

# Build for production
parcel build index.html
# ✨ Built in 456ms
# dist/index.html      1.23 KB    123ms
# dist/app.js          2.45 KB      0ms

Architecture

Parcel operates as a command-line tool that orchestrates the build process through several key components:

  • CLI Interface: Command-line commands (serve, watch, build, help) that accept various options
  • Development Server: Built-in dev server with hot module replacement for development workflow
  • Build Pipeline: Production build system with optimizations like minification and tree-shaking
  • File System Watcher: Monitors file changes for automatic rebuilds in development
  • Configuration System: Zero-config approach with optional configuration files

Capabilities

Development Server

Start a development server with hot module replacement for rapid development workflow.

parcel serve [input...]
# or simply:
parcel [input...]

# Common options:
# --port <port>          Set server port (default: 1234)
# --host <host>          Set host to listen on
# --https                Serve files over HTTPS
# --cert <path>          Path to HTTPS certificate
# --key <path>           Path to HTTPS private key
# --open [browser]       Auto-open in browser
# --public-url <url>     Path prefix for absolute URLs
# --lazy [includes]      Build async bundles on demand, when requested in the browser
# --lazy-exclude <excludes>  Can only be used with --lazy. Exclude from lazy building
# --watch-for-stdin      Exit when stdin closes

Usage Examples:

# Basic development server
parcel index.html

# Custom port and host
parcel serve src/index.html --port 3000 --host 0.0.0.0

# HTTPS development server
parcel index.html --https --cert ./cert.pem --key ./key.pem

# Auto-open in default browser
parcel index.html --open

# Lazy loading for large applications
parcel index.html --lazy "src/pages/**/*.js"

# Lazy loading with exclusions
parcel index.html --lazy --lazy-exclude "src/critical/**/*.js"

Production Build

Bundle application for production with optimizations enabled.

parcel build [input...]

# Common options:
# --no-optimize         Disable minification
# --no-scope-hoist      Disable scope-hoisting  
# --public-url <url>    Path prefix for absolute URLs
# --no-content-hash     Disable content hashing
# --dist-dir <dir>      Output directory
# --target [name]       Build specific targets

Usage Examples:

# Basic production build
parcel build index.html

# Custom output directory
parcel build src/index.html --dist-dir build

# Disable optimizations for debugging
parcel build index.html --no-optimize --no-scope-hoist

# Build for specific targets
parcel build index.html --target web --target node

# Custom public URL for CDN deployment
parcel build index.html --public-url https://cdn.example.com/

Watch Mode

Monitor files for changes and rebuild automatically without development server.

parcel watch [input...]

# Common options:
# --public-url <url>    Path prefix for absolute URLs
# --no-content-hash     Disable content hashing
# --watch-for-stdin     Exit when stdin closes

# HMR options (same as serve command):
# --no-hmr              Disable hot module replacement
# --hmr-port <port>     Hot module replacement port
# --hmr-host <host>     Hot module replacement host

Usage Examples:

# Basic watch mode
parcel watch index.html

# Watch with custom settings
parcel watch src/index.html --no-content-hash --public-url /assets/

Help System

Get help information for commands and options.

parcel help [command]

# Examples:
parcel help           # General help
parcel help serve     # Help for serve command
parcel help build     # Help for build command

Global Options

These options are available across all commands:

Cache & Performance

# Cache control
--no-cache              # Disable filesystem cache
--cache-dir <path>      # Set cache directory (default: .parcel-cache)

# Performance monitoring
--profile               # Enable sampling build profiling
--trace                 # Enable build tracing
--detailed-report [count]  # Print asset timings and sizes

File Watching

# Watch configuration
--watch-dir <path>      # Set root watch directory (defaults to nearest lockfile or source control dir)
--watch-ignore [paths]  # Directories to ignore (comma-separated, defaults to '.git,.hg')
--watch-backend <name>  # Set watcher backend
                       # Choices: brute-force, watchman, fs-events, inotify, windows

Build Configuration

# Configuration
--config <path>         # Specify config path or package name
--no-source-maps        # Disable sourcemaps
--target [name]         # Build specific targets (can be used multiple times)
--no-autoinstall        # Disable automatic dependency installation

Hot Module Replacement

# HMR configuration (serve/watch commands)
--no-hmr               # Disable hot module replacement
--hmr-port <port>      # Hot module replacement port
--hmr-host <host>      # Hot module replacement host

Logging & Reporting

# Logging
--log-level <level>    # Set log level
                      # Choices: none, error, warn, info, verbose

# Reporting
--reporter <name>      # Additional reporters (can be used multiple times)

Feature Flags

# Feature flags
--feature-flag <name=value>  # Set feature flag values
                            # Format: --feature-flag name=true
                            # Available flags: exampleFeature, useWatchmanWatcher

Version Information

# Version
-V, --version          # Output version number

Entry Point Discovery

Parcel automatically discovers entry points based on file extensions and content:

  • HTML files: index.html, src/index.html
  • JavaScript/TypeScript: index.js, main.js, app.js, src/index.ts
  • Package.json: Uses main, module, or browser fields
  • Multiple entries: parcel build src/*.html for multiple pages

Target Environments

Parcel supports multiple build targets:

  • Web browsers: Modern ES modules and legacy compatibility
  • Node.js: Server-side applications and utilities
  • Electron: Desktop applications
  • Web Workers: Background processing scripts

Configuration Files

While zero-config by default, Parcel supports optional configuration:

  • .parcelrc: Main configuration file
  • package.json: Browserslist, source fields
  • tsconfig.json: TypeScript configuration
  • postcss.config.js: PostCSS configuration

Error Handling

Parcel provides detailed error messages and diagnostics:

  • Build errors: Syntax errors, missing dependencies, type errors
  • Runtime errors: Hot reload error overlay in development
  • Performance warnings: Bundle size, unused dependencies
  • Detailed stack traces: Source map support for debugging

Runtime Controls

While Parcel is running, these keyboard shortcuts are available:

# Keyboard shortcuts during runtime
Ctrl+C    # Graceful exit
Ctrl+E    # Toggle profiling
Ctrl+Y    # Take heap snapshot

Environment Variables

Parcel recognizes several environment variables:

  • NODE_ENV: Automatically set based on command (development for serve/watch, production for build)
  • PORT: Default port for development server (defaults to 1234)
  • HMR_PORT: Default HMR port
  • HMR_HOST: Default HMR host
  • CI: When detected, disables autoinstall for build command
  • PARCEL_BUILD_ENV: Internal build environment control

Port Behavior

Parcel handles ports intelligently:

  • Default port: 1234 or value from $PORT environment variable
  • Port occupied: Automatically finds next available port
  • User-specified port: Fails if port is not available (no auto-discovery)
  • HMR port: Separate port for hot module replacement (from $HMR_PORT)

Mode Detection

Parcel automatically sets the build mode:

  • Production mode: parcel build command (enables optimizations)
  • Development mode: parcel serve and parcel watch commands (enables debugging features)

Install with Tessl CLI

npx tessl i tessl/npm-parcel

docs

index.md

tile.json