Parcel Compressor Gzip

@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.

Package Information

• Package Name: @parcel/compressor-gzip
• Package Type: npm
• Language: JavaScript (Flow types)
• Installation: npm install @parcel/compressor-gzip
• Parcel Version: Requires Parcel ^2.15.4
• Node.js Version: Requires Node.js >= 16.0.0

Core Imports

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.

// Direct import (rarely needed)
import GzipCompressor from "@parcel/compressor-gzip";

For CommonJS:

const GzipCompressor = require("@parcel/compressor-gzip");

Basic Usage

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

// Parcel configuration (.parcelrc)
{
  "extends": "@parcel/config-default",
  "compressors": {
    "*": ["@parcel/compressor-gzip", "..."]
  }
}

Architecture

The plugin implements Parcel's Compressor interface:

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

Capabilities

Gzip Compression

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

/**
 * Pre-configured Parcel Compressor plugin instance
 * Implements the Parcel Compressor interface
 */
declare const GzipCompressor: Compressor;

export default GzipCompressor;

// Compressor interface definition
type Compressor = {|
  compress({|
    stream: Readable,
    options: PluginOptions,
    logger: PluginLogger,
    tracer: PluginTracer,
  |}): Async<?{|
    stream: Readable,
    type?: string,
  |}>,
|};

Compression Implementation

The plugin implements Parcel's compress method:

/**
 * Compresses input streams using gzip when in production mode
 * @param options - Parcel plugin options including build mode and file system access
 * @param stream - Node.js readable stream containing input data
 * @param logger - Plugin logger for diagnostics and debugging
 * @param tracer - Plugin tracer for performance measurement
 * @returns Promise or sync result with compressed stream object or null if not in production
 */
compress({|
  options: PluginOptions,
  stream: Readable,
  logger: PluginLogger,
  tracer: PluginTracer,
|}): Async<?{|
  stream: Readable,
  type?: string,
|}>;

Parameters:

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

Returns:

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

Behavior:

• Only compresses in production builds (options.mode === 'production')
• Uses maximum compression level (level 9) for optimal file size reduction
• Streams data through gzip compression for memory efficiency
• Outputs compressed files with .gz extension

Types

// Parcel plugin interfaces (from @parcel/plugin)
interface PluginOptions {
  +mode: BuildMode;
  +parcelVersion: string;
  +env: EnvMap;
  +hmrOptions: ?HMROptions;
  +serveOptions: ServerOptions | false;
  +shouldBuildLazily: boolean;
  +shouldAutoInstall: boolean;
  +logLevel: LogLevel;
  +projectRoot: FilePath;
  +cacheDir: FilePath;
  +inputFS: FileSystem;
  +outputFS: FileSystem;
  +packageManager: PackageManager;
  +instanceId: string;
  +detailedReport: ?DetailedReportOptions;
  +featureFlags: FeatureFlags;
}

interface PluginLogger {
  /** Logs a diagnostic at the verbose log level. */
  verbose(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void;
  /** Logs a diagnostic at the info log level. */
  info(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void;
  /** Synonym for logger.info. */
  log(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void;
  /** Logs a diagnostic at the warning log level. */
  warn(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void;
  /** Logs a diagnostic at the error log level. */
  error(input: Diagnostifiable | DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void;
}

interface PluginTracer {
  /** Returns whether the tracer is enabled. */
  +enabled: boolean;
  /**
   * Creates a new trace measurement with the specified name.
   * Returns TraceMeasurement | null.
   */
  createMeasurement(
    name: string,
    category?: string,
    argumentName?: string,
    otherArgs?: {[key: string]: mixed},
  ): TraceMeasurement | null;
}

interface TraceMeasurement {
  end(): void;
}

// Utility types
type Async<T> = T | Promise<T>;
type BuildMode = 'development' | 'production' | string;
type FilePath = string;

// Node.js types (from Node.js)
interface Readable {
  pipe<T extends NodeJS.WritableStream>(destination: T, options?: { end?: boolean }): T;
  // ... standard Node.js Readable stream interface
}

Dependencies

The plugin has the following dependencies:

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

Configuration

The plugin uses fixed configuration:

• Compression Level: Always level 9 (maximum compression)
• File Extension: Always '.gz'
• Mode Dependency: Only active in production builds
• Stream Processing: Always uses Node.js streams for memory efficiency

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