Parcel Bundler

You are an expert in Parcel, the zero-configuration build tool for the web. Follow these guidelines when working with Parcel projects.

Core Principles

Zero configuration by default - Parcel works out of the box
Automatic dependency detection and installation
Built-in development server with hot module replacement
Native performance with Rust-based compiler
Automatic code splitting and optimization

Project Structure

project/
├── src/
│   ├── index.html        # HTML entry point
│   ├── index.js          # JavaScript entry
│   ├── styles.css        # Stylesheets
│   └── assets/           # Images, fonts, etc.
├── dist/                 # Build output (auto-generated)
├── .parcelrc             # Optional configuration
└── package.json

Getting Started

Basic Usage

bash

# Development with hot reload
parcel src/index.html

# Production build
parcel build src/index.html

Package.json Scripts

json

{
  "scripts": {
    "dev": "parcel src/index.html",
    "build": "parcel build src/index.html",
    "clean": "rm -rf dist .parcel-cache"
  },
  "source": "src/index.html"
}

Entry Points

HTML Entry

html

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="./styles.css">
</head>
<body>
  <div id="app"></div>
  <script type="module" src="./index.js"></script>
</body>
</html>

JavaScript Entry

bash

parcel build src/index.js --dist-dir lib

Multiple Entry Points

bash

parcel build src/index.html src/admin.html

Supported Languages and File Types

Parcel supports out of the box:

JavaScript/TypeScript:
```
.js
```
,
```
.jsx
```
,
```
.ts
```
,
```
.tsx
```
,
```
.mjs
```
Styles:
```
.css
```
,
```
.scss
```
,
```
.sass
```
,
```
.less
```
,
```
.styl
```
HTML:
```
.html
```
,
```
.htm
```
Images:
```
.png
```
,
```
.jpg
```
,
```
.gif
```
,
```
.svg
```
,
```
.webp
```
Fonts:
```
.woff
```
,
```
.woff2
```
,
```
.ttf
```
,
```
.otf
```
,
```
.eot
```
Data:
```
.json
```
,
```
.yaml
```
,
```
.toml
```
,
```
.xml
```
WebAssembly:
```
.wasm
```

Configuration (When Needed)

.parcelrc

json

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.svg": ["@parcel/transformer-svg-react"]
  },
  "reporters": ["...", "parcel-reporter-bundle-analyzer"]
}

package.json Targets

json

{
  "targets": {
    "main": {
      "source": "src/index.js",
      "distDir": "dist",
      "context": "browser",
      "outputFormat": "esm"
    }
  }
}

TypeScript Support

Automatic Configuration

Parcel handles TypeScript automatically. Just use

.ts

.tsx

files.

tsconfig.json

json

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "isolatedModules": true
  }
}

React Support

Automatic JSX

jsx

// Parcel handles JSX automatically
import { useState } from 'react';

function App() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}

CSS and Styling

CSS Imports

javascript

import './styles.css';

CSS Modules

javascript

import * as styles from './Button.module.css';

function Button() {
  return <button className={styles.primary}>Click me</button>;
}

Sass/SCSS

javascript

import './styles.scss';

Parcel installs

sass

automatically when you use

.scss

files.

Asset Handling

Importing Assets

javascript

import logo from './logo.png';
import data from './data.json';

// Use in JSX
<img src={logo} alt="Logo" />

URL References

javascript

const imageUrl = new URL('./image.png', import.meta.url);

Code Splitting

Dynamic Imports

javascript

// Automatic code splitting
const LazyComponent = React.lazy(() => import('./LazyComponent'));

// Or manual
async function loadModule() {
  const module = await import('./heavy-module.js');
  return module.default;
}

Shared Bundles

Parcel automatically creates shared bundles for code used across multiple entry points.

Environment Variables

.env Files

# .env
API_URL=https://api.example.com

# .env.production
API_URL=https://api.production.com

Usage in Code

javascript

const apiUrl = process.env.API_URL;

Defining in package.json

json

{
  "targets": {
    "default": {
      "publicUrl": "/my-app/"
    }
  }
}

Development Server

Default Configuration

bash

parcel src/index.html
# Serves at http://localhost:1234

Custom Port

bash

parcel src/index.html --port 3000

HTTPS

bash

parcel src/index.html --https

Proxy API Requests

json

{
  "devServer": {
    "proxy": {
      "/api": {
        "target": "http://localhost:8080"
      }
    }
  }
}

Production Build

Basic Build

bash

parcel build src/index.html

Output Configuration

bash

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

No Source Maps

bash

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

Optimization

Automatic Optimizations

Parcel automatically:

Minifies JavaScript, CSS, HTML, and SVG
Compresses images
Generates content hashes for caching
Tree-shakes unused code
Scope hoists modules

Bundle Analysis

bash

npm install -D parcel-reporter-bundle-analyzer

# Add to .parcelrc
{
  "extends": "@parcel/config-default",
  "reporters": ["...", "parcel-reporter-bundle-analyzer"]
}

Caching

Parcel uses aggressive caching:

bash

# Clear cache
rm -rf .parcel-cache

# Or
parcel build --no-cache

Plugin Development

Plugin Types

Transformers: Transform source files
Resolvers: Custom module resolution
Bundlers: Custom bundling logic
Namers: Custom output naming
Packagers: Package bundles
Optimizers: Optimize bundles
Reporters: Custom build reporting

Plugin Rules

Stateless: Avoid internal state
Pure: Same input produces same output
No side effects: Don't modify external state

Library Development

Package.json Configuration

json

{
  "name": "my-library",
  "source": "src/index.ts",
  "main": "dist/main.js",
  "module": "dist/module.js",
  "types": "dist/types.d.ts",
  "targets": {
    "main": {
      "outputFormat": "commonjs"
    },
    "module": {
      "outputFormat": "esmodule"
    },
    "types": {
      "source": "src/index.ts"
    }
  }
}

Best Practices

Do

Start with zero configuration
Let Parcel handle asset optimization
Use dynamic imports for code splitting
Leverage automatic dependency installation
Use CSS Modules for component styles

Avoid

Over-configuring when defaults work
Fighting against Parcel's conventions
Manually optimizing what Parcel handles
Ignoring build warnings and errors

Common Patterns

Single Page Application

html

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>My App</title>
</head>
<body>
  <div id="root"></div>
  <script type="module" src="./index.tsx"></script>
</body>
</html>

Static Site

bash

parcel build src/*.html

Web Worker

javascript

const worker = new Worker(new URL('./worker.js', import.meta.url), {
  type: 'module'
});

Troubleshooting

Clear Cache

bash

rm -rf .parcel-cache dist

Verbose Output

bash

parcel build --log-level verbose

Debug Mode

bash

DEBUG=parcel:* parcel build

Migration from Other Bundlers

Remove webpack.config.js or similar
Remove loader/plugin dependencies
Update import statements if needed
Parcel will auto-install required dependencies

parcel-bundler

NPX Install

Tags

SKILL.md Content

Parcel Bundler

Core Principles

Project Structure

Getting Started

Basic Usage

Package.json Scripts

Entry Points

HTML Entry

JavaScript Entry

Multiple Entry Points

Supported Languages and File Types

Configuration (When Needed)

.parcelrc

package.json Targets

TypeScript Support

Automatic Configuration

tsconfig.json

React Support

Automatic JSX

CSS and Styling

CSS Imports

CSS Modules

Sass/SCSS

Asset Handling

Importing Assets

URL References

Code Splitting

Dynamic Imports

Shared Bundles

Environment Variables

.env Files

Usage in Code

Defining in package.json

Development Server

Default Configuration

Custom Port

HTTPS

Proxy API Requests

Production Build

Basic Build

Output Configuration

No Source Maps

Optimization

Automatic Optimizations

Bundle Analysis

Caching

Plugin Development

Plugin Types

Plugin Rules

Library Development

Package.json Configuration

Best Practices

Do

Avoid

Common Patterns

Single Page Application

Static Site

Web Worker

Troubleshooting

Clear Cache

Verbose Output

Debug Mode

Migration from Other Bundlers