0
# Parcel Bundler
1

2
Parcel is a blazing fast, zero configuration web application bundler that provides multicore compilation and intelligent caching. It offers out-of-the-box support for JavaScript, CSS, HTML, and various file assets without requiring plugins, automatically transforms modules using Babel, PostCSS, and PostHTML, and includes built-in support for code splitting via dynamic imports and hot module replacement for development.
3

4
## Package Information
5

6
- **Package Name**: parcel-bundler
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install parcel-bundler`
10

11
## Core Imports
12

13
```javascript
14
const Bundler = require('parcel-bundler');
15
```
16

17
For ES modules:
18

19
```javascript
20
import Bundler from 'parcel-bundler';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const Bundler = require('parcel-bundler');
27
const path = require('path');
28

29
// Entry file for bundling
30
const entryFiles = path.join(__dirname, './src/index.html');
31

32
// Bundler options
33
const options = {
34
  outDir: './dist', // Output directory
35
  outFile: 'index.html', // Output filename
36
  publicURL: './', // Public URL path
37
  watch: true, // Enable file watching
38
  cache: true, // Enable caching
39
  minify: false, // Disable minification for development
40
  target: 'browser', // Build target
41
  logLevel: 3, // Log level (0-5)
42
  hmr: true, // Enable hot module replacement
43
  sourceMaps: true, // Enable source maps
44
};
45

46
// Initialize bundler
47
const bundler = new Bundler(entryFiles, options);
48

49
// Start development server
50
bundler.serve(1234, false, 'localhost').then(server => {
51
  console.log('Server started on http://localhost:1234');
52
});
53

54
// Or build for production
55
bundler.bundle().then(bundle => {
56
  console.log('Build completed!');
57
});
58
```
59

60
## Architecture
61

62
Parcel is built around several key components:
63

64
- **Bundler Class**: Main orchestrator that manages the bundling process, asset resolution, and build pipeline
65
- **Asset System**: Extensible asset processing system with 25+ built-in asset types for different file formats
66
- **Packaging System**: Collection of packagers that generate final output bundles for different target types
67
- **CLI Interface**: Command-line tool providing serve, watch, build, and info commands with extensive options
68
- **Development Tools**: Built-in development server with HMR (Hot Module Replacement) and file watching
69
- **Caching System**: Intelligent filesystem caching for fast incremental builds
70

71
## Capabilities
72

73
### Programmatic Bundler API
74

75
Core Bundler class for programmatic control over the bundling process, including configuration options, lifecycle management, and custom asset/packager registration.
76

77
```javascript { .api }
78
class Bundler extends EventEmitter {
79
  constructor(entryFiles, options = {});
80
  addAssetType(extension, path);
81
  addPackager(type, packager);
82
  addBundleLoader(type, paths);
83
  bundle();
84
  serve(port, https, host);
85
  middleware();
86
  start();
87
  stop();
88
}
89
```
90

91
[Bundler API](./bundler-api.md)
92

93
### Command Line Interface
94

95
Comprehensive CLI tool with commands for development server, file watching, production builds, and environment debugging.
96

97
```bash { .api }
98
parcel serve [input...]     # Start development server (default)
99
parcel watch [input...]     # Start bundler in watch mode  
100
parcel build [input...]     # Build for production
101
parcel info                 # Print debugging information
102
parcel help [command]       # Display help information
103
```
104

105
[Command Line Interface](./cli.md)
106

107
### Asset Processing System
108

109
Extensible asset processing system supporting 25+ file types including JavaScript variants, stylesheets, markup languages, and data formats with automatic transforms and dependency resolution.
110

111
```javascript { .api }
112
class Asset {
113
  constructor(name, options);
114
  load();
115
  parse(code);
116
  collectDependencies();
117
  transform();
118
  generate();
119
  addDependency(name, opts);
120
}
121
```
122

123
[Asset System](./asset-system.md)
124

125
## Types
126

127
```javascript { .api }
128
// Bundler Options
129
interface BundlerOptions {
130
  outDir?: string;           // Output directory (default: 'dist')
131
  outFile?: string;          // Output filename
132
  publicURL?: string;        // Public URL path (default: '/')
133
  watch?: boolean;           // Watch mode
134
  cache?: boolean;           // Enable caching (default: true)
135
  cacheDir?: string;         // Cache directory (default: '.cache')
136
  minify?: boolean;          // Minify output
137
  target?: string;           // Build target: 'browser', 'node', 'electron'
138
  bundleNodeModules?: boolean; // Bundle node_modules
139
  hmr?: boolean;             // Hot module replacement
140
  https?: boolean | object;  // HTTPS configuration
141
  sourceMaps?: boolean;      // Generate source maps (default: true)
142
  logLevel?: number;         // Logging level (0-5)
143
  autoinstall?: boolean;     // Auto-install dependencies
144
  scopeHoist?: boolean;      // Scope hoisting/tree shaking
145
  contentHash?: boolean;     // Content hashing for file names
146
}
147

148
// Bundle representation
149
interface Bundle {
150
  type: string;              // Bundle type (js, css, html, etc.)
151
  name: string;              // Output file path
152
  assets: Set;               // Set of assets in bundle
153
  childBundles: Set;         // Set of child bundles
154
  entryAsset: Asset;         // Main asset for this bundle
155
}
156

157
// Asset representation
158
interface Asset {
159
  name: string;              // Absolute file path
160
  type: string;              // File extension without dot
161
  contents: string;          // Raw file contents
162
  ast: object;               // Parsed AST
163
  dependencies: Map;         // Map of dependencies
164
  generated: object;         // Generated output per target type
165
  parentBundle: Bundle;      // Bundle containing this asset
166
}
167
```