0
# Parcel Brotli Compressor
1

2
Brotli compression plugin for Parcel bundler that provides optimized file compression using the Brotli algorithm in production builds. This plugin integrates seamlessly with Parcel's plugin architecture to enable high-efficiency compression utilizing Node.js's built-in zlib module.
3

4
## Package Information
5

6
- **Package Name**: @parcel/compressor-brotli
7
- **Package Type**: npm
8
- **Language**: JavaScript (Flow-typed)
9
- **Installation**: `npm install @parcel/compressor-brotli`
10
- **Node.js Version**: >= 16.0.0
11
- **Parcel Version**: ^2.15.4
12

13
## Core Imports
14

15
```javascript
16
// Default import - the only public export
17
import BrotliCompressor from "@parcel/compressor-brotli";
18
```
19

20
For CommonJS:
21

22
```javascript
23
const BrotliCompressor = require("@parcel/compressor-brotli");
24
```
25

26
## Basic Usage
27

28
This plugin is designed for automatic usage within Parcel's build pipeline and does not require direct instantiation by end users. Parcel automatically loads and uses this compressor during production builds when configured.
29

30
```javascript
31
// Parcel configuration example (.parcelrc)
32
{
33
  "extends": "@parcel/config-default",
34
  "compressors": {
35
    "*.{js,css,html,svg}": ["@parcel/compressor-brotli", "..."]
36
  }
37
}
38
```
39

40
## Architecture
41

42
The plugin follows Parcel's standard plugin architecture:
43

44
- **Base Class**: Extends `Compressor` from `@parcel/plugin`
45
- **Compression Method**: Uses Node.js `zlib.createBrotliCompress()` with maximum quality settings
46
- **Mode Restriction**: Only active in production mode (returns `null` in development)
47
- **Output**: Streams compressed data with 'br' content encoding type
48

49
## Capabilities
50

51
### Brotli Compression
52

53
The default export provides a pre-configured Brotli compressor instance that automatically compresses files during Parcel's production build process.
54

55
```javascript { .api }
56
/**
57
 * Pre-configured Brotli compressor instance for Parcel bundler
58
 * @type {Compressor}
59
 */
60
declare const BrotliCompressor: Compressor;
61

62
export default BrotliCompressor;
63
```
64

65
### Compress Method
66

67
The compress method from the base Compressor class, which this plugin implements.
68

69
```javascript { .api }
70
interface Compressor {
71
  compress(params: CompressParams): Promise<CompressResult | null>;
72
}
73
```
74

75
## Types
76

77
```javascript { .api }
78
/**
79
 * Base Compressor class from @parcel/plugin
80
 */
81
interface Compressor {
82
  compress(params: CompressParams): Promise<CompressResult | null>;
83
}
84

85
/**
86
 * Parameters passed to the compress method
87
 */
88
interface CompressParams {
89
  /** Stream of content to compress */
90
  stream: Readable;
91
  /** Plugin options including build mode */
92
  options: PluginOptions;
93
  /** Logger instance for diagnostics */
94
  logger: PluginLogger;
95
  /** Tracer instance for performance monitoring */
96
  tracer: PluginTracer;
97
}
98

99
/**
100
 * Plugin options containing build configuration
101
 */
102
interface PluginOptions {
103
  /** Build mode - 'development' or 'production' */
104
  mode: 'development' | 'production';
105
}
106

107
/**
108
 * Result of compression operation
109
 */
110
interface CompressResult {
111
  /** Compressed content stream */
112
  stream: Readable;
113
  /** Content encoding type ('br' for Brotli) */
114
  type?: string;
115
}
116

117
/**
118
 * Logger interface for plugin diagnostics
119
 */
120
interface PluginLogger {
121
  /** Logs a diagnostic at the verbose log level */
122
  verbose(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void;
123
  /** Logs a diagnostic at the info log level */
124
  info(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void;
125
  /** Logs a diagnostic at the warn log level */
126
  warn(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void;
127
  /** Logs a diagnostic at the error log level */
128
  error(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void;
129
}
130

131
/**
132
 * Tracer interface for performance monitoring
133
 */
134
interface PluginTracer {
135
  /** Returns whether the tracer is enabled */
136
  enabled: boolean;
137
  /** Create a measurement for performance tracking */
138
  createMeasurement(name: string, category?: string, argumentName?: string): any;
139
}
140

141
/**
142
 * Diagnostic message without origin information
143
 */
144
interface DiagnosticWithoutOrigin {
145
  /** The diagnostic message */
146
  message: string;
147
  /** Optional hints for fixing the issue */
148
  hints?: Array<string>;
149
  /** Optional documentation URL for more information */
150
  documentationURL?: string;
151
}
152
```
153

154
## Behavior
155

156
### Development Mode
157
- Returns `null` (no compression applied)
158
- Allows faster build times during development
159

160
### Production Mode
161
- Creates Brotli compressed stream using maximum quality settings
162
- Uses `zlib.constants.BROTLI_MAX_QUALITY` for optimal compression
163
- Returns compressed stream with `type: 'br'` content encoding
164
- Generates `.br` files alongside original files
165

166
### Compression Settings
167
- **Quality**: Maximum (`zlib.constants.BROTLI_MAX_QUALITY`)
168
- **Algorithm**: Brotli via Node.js `zlib.createBrotliCompress()`
169
- **Content Type**: 'br' (standard Brotli encoding identifier)
170

171
## Integration
172

173
This plugin works in conjunction with:
174
- **Parcel's plugin system**: Automatic loading and execution
175
- **Other compressors**: Can be used alongside gzip compression
176
- **Build pipeline**: Integrates with Parcel's asset processing workflow
177
- **File types**: Compresses JavaScript, CSS, HTML, SVG, and source maps
178

179
## Error Handling
180

181
The plugin handles errors through Parcel's standard plugin error reporting system. Common scenarios:
182
- **Compression failures**: Logged through the provided logger instance
183
- **Stream errors**: Propagated through the returned stream
184
- **Configuration issues**: Handled by Parcel's plugin loader