0
# Parcel Compressor Gzip
1

2
@parcel/compressor-gzip is a Parcel plugin that provides gzip compression for production builds using Node.js zlib module with maximum compression level. It extends the Parcel plugin architecture to compress build outputs, outputting files with '.gz' extension for improved web performance.
3

4
## Package Information
5

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

13
## Core Imports
14

15
This package exports a pre-configured Parcel Compressor plugin instance. It is typically not imported directly by user code, but rather consumed by Parcel's plugin system.
16

17
```javascript
18
// Direct import (rarely needed)
19
import GzipCompressor from "@parcel/compressor-gzip";
20
```
21

22
For CommonJS:
23

24
```javascript
25
const GzipCompressor = require("@parcel/compressor-gzip");
26
```
27

28
## Basic Usage
29

30
The plugin automatically activates during Parcel builds when installed. No direct usage is required - Parcel's plugin system handles instantiation and execution.
31

32
```javascript
33
// Parcel configuration (.parcelrc)
34
{
35
  "extends": "@parcel/config-default",
36
  "compressors": {
37
    "*": ["@parcel/compressor-gzip", "..."]
38
  }
39
}
40
```
41

42
## Architecture
43

44
The plugin implements Parcel's Compressor interface:
45

46
- **Plugin Type**: Compressor plugin extending Parcel's plugin architecture
47
- **Activation**: Automatic when installed and Parcel is in production mode
48
- **Processing**: Transforms streams through gzip compression without loading entire files into memory
49
- **Integration**: Seamlessly integrates with Parcel's build pipeline
50
- **Output**: Creates compressed versions with '.gz' extension alongside original files
51

52
## Capabilities
53

54
### Gzip Compression
55

56
Provides gzip compression for production builds using Node.js zlib with maximum compression level.
57

58
```javascript { .api }
59
/**
60
 * Pre-configured Parcel Compressor plugin instance
61
 * Implements the Parcel Compressor interface
62
 */
63
declare const GzipCompressor: Compressor;
64

65
export default GzipCompressor;
66

67
// Compressor interface definition
68
type Compressor = {|
69
  compress({|
70
    stream: Readable,
71
    options: PluginOptions,
72
    logger: PluginLogger,
73
    tracer: PluginTracer,
74
  |}): Async<?{|
75
    stream: Readable,
76
    type?: string,
77
  |}>,
78
|};
79
```
80

81
### Compression Implementation
82

83
The plugin implements Parcel's compress method:
84

85
```javascript { .api }
86
/**
87
 * Compresses input streams using gzip when in production mode
88
 * @param options - Parcel plugin options including build mode and file system access
89
 * @param stream - Node.js readable stream containing input data
90
 * @param logger - Plugin logger for diagnostics and debugging
91
 * @param tracer - Plugin tracer for performance measurement
92
 * @returns Promise or sync result with compressed stream object or null if not in production
93
 */
94
compress({|
95
  options: PluginOptions,
96
  stream: Readable,
97
  logger: PluginLogger,
98
  tracer: PluginTracer,
99
|}): Async<?{|
100
  stream: Readable,
101
  type?: string,
102
|}>;
103
```
104

105
**Parameters:**
106
- `options`: Complete Parcel plugin options including build mode, file systems, and configuration
107
  - `options.mode`: Build mode - compression only activates when mode === 'production'
108
  - `options.inputFS`, `options.outputFS`: File system interfaces for reading/writing
109
  - `options.projectRoot`, `options.cacheDir`: Directory paths for project structure
110
- `stream`: Node.js Readable stream containing the input data to compress
111
- `logger`: Plugin logger instance for verbose, info, warning, and error diagnostics
112
- `tracer`: Plugin tracer instance for creating performance measurements
113

114
**Returns:**
115
- `Async<?{| stream: Readable, type?: string |}>` - Can be synchronous or Promise-based
116
- `null` when not in production mode (no compression applied)
117
- `{stream: Readable, type: 'gz'}` when in production mode
118
  - `stream`: Compressed stream created via `stream.pipe(zlib.createGzip({level: 9}))`
119
  - `type`: Optional string `'gz'` indicating compressed file extension
120

121
**Behavior:**
122
- Only compresses in production builds (`options.mode === 'production'`)
123
- Uses maximum compression level (level 9) for optimal file size reduction
124
- Streams data through gzip compression for memory efficiency
125
- Outputs compressed files with `.gz` extension
126

127
## Types
128

129
```javascript { .api }
130
// Parcel plugin interfaces (from @parcel/plugin)
131
interface PluginOptions {
132
  +mode: BuildMode;
133
  +parcelVersion: string;
134
  +env: EnvMap;
135
  +hmrOptions: ?HMROptions;
136
  +serveOptions: ServerOptions | false;
137
  +shouldBuildLazily: boolean;
138
  +shouldAutoInstall: boolean;
139
  +logLevel: LogLevel;
140
  +projectRoot: FilePath;
141
  +cacheDir: FilePath;
142
  +inputFS: FileSystem;
143
  +outputFS: FileSystem;
144
  +packageManager: PackageManager;
145
  +instanceId: string;
146
  +detailedReport: ?DetailedReportOptions;
147
  +featureFlags: FeatureFlags;
148
}
149

150
interface PluginLogger {
151
  /** Logs a diagnostic at the verbose log level. */
152
  verbose(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void;
153
  /** Logs a diagnostic at the info log level. */
154
  info(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void;
155
  /** Synonym for logger.info. */
156
  log(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void;
157
  /** Logs a diagnostic at the warning log level. */
158
  warn(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void;
159
  /** Logs a diagnostic at the error log level. */
160
  error(input: Diagnostifiable | DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void;
161
}
162

163
interface PluginTracer {
164
  /** Returns whether the tracer is enabled. */
165
  +enabled: boolean;
166
  /**
167
   * Creates a new trace measurement with the specified name.
168
   * Returns TraceMeasurement | null.
169
   */
170
  createMeasurement(
171
    name: string,
172
    category?: string,
173
    argumentName?: string,
174
    otherArgs?: {[key: string]: mixed},
175
  ): TraceMeasurement | null;
176
}
177

178
interface TraceMeasurement {
179
  end(): void;
180
}
181

182
// Utility types
183
type Async<T> = T | Promise<T>;
184
type BuildMode = 'development' | 'production' | string;
185
type FilePath = string;
186

187
// Node.js types (from Node.js)
188
interface Readable {
189
  pipe<T extends NodeJS.WritableStream>(destination: T, options?: { end?: boolean }): T;
190
  // ... standard Node.js Readable stream interface
191
}
192
```
193

194
## Dependencies
195

196
The plugin has the following dependencies:
197

198
- `@parcel/plugin`: Provides the base Compressor class and plugin interfaces
199
- `zlib` (Node.js built-in): Provides gzip compression functionality via `createGzip()`
200

201
## Configuration
202

203
The plugin uses fixed configuration:
204

205
- **Compression Level**: Always level 9 (maximum compression)
206
- **File Extension**: Always '.gz'
207
- **Mode Dependency**: Only active in production builds
208
- **Stream Processing**: Always uses Node.js streams for memory efficiency
209

210
No runtime configuration options are available - the plugin behavior is fixed for consistent, optimal compression.