or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-parcel--compressor-brotli

Brotli compression plugin for Parcel bundler that provides optimized file compression using the Brotli algorithm in production builds

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@parcel/compressor-brotli@2.15.x

To install, run

npx @tessl/cli install tessl/npm-parcel--compressor-brotli@2.15.0

index.mddocs/

Parcel Brotli Compressor

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.

Package Information

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

Core Imports

// Default import - the only public export
import BrotliCompressor from "@parcel/compressor-brotli";

For CommonJS:

const BrotliCompressor = require("@parcel/compressor-brotli");

Basic Usage

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.

// Parcel configuration example (.parcelrc)
{
  "extends": "@parcel/config-default",
  "compressors": {
    "*.{js,css,html,svg}": ["@parcel/compressor-brotli", "..."]
  }
}

Architecture

The plugin follows Parcel's standard plugin architecture:

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

Capabilities

Brotli Compression

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

/**
 * Pre-configured Brotli compressor instance for Parcel bundler
 * @type {Compressor}
 */
declare const BrotliCompressor: Compressor;

export default BrotliCompressor;

Compress Method

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

interface Compressor {
  compress(params: CompressParams): Promise<CompressResult | null>;
}

Types

/**
 * Base Compressor class from @parcel/plugin
 */
interface Compressor {
  compress(params: CompressParams): Promise<CompressResult | null>;
}

/**
 * Parameters passed to the compress method
 */
interface CompressParams {
  /** Stream of content to compress */
  stream: Readable;
  /** Plugin options including build mode */
  options: PluginOptions;
  /** Logger instance for diagnostics */
  logger: PluginLogger;
  /** Tracer instance for performance monitoring */
  tracer: PluginTracer;
}

/**
 * Plugin options containing build configuration
 */
interface PluginOptions {
  /** Build mode - 'development' or 'production' */
  mode: 'development' | 'production';
}

/**
 * Result of compression operation
 */
interface CompressResult {
  /** Compressed content stream */
  stream: Readable;
  /** Content encoding type ('br' for Brotli) */
  type?: string;
}

/**
 * Logger interface for plugin diagnostics
 */
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;
  /** Logs a diagnostic at the warn log level */
  warn(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void;
  /** Logs a diagnostic at the error log level */
  error(diagnostic: DiagnosticWithoutOrigin | Array<DiagnosticWithoutOrigin>): void;
}

/**
 * Tracer interface for performance monitoring
 */
interface PluginTracer {
  /** Returns whether the tracer is enabled */
  enabled: boolean;
  /** Create a measurement for performance tracking */
  createMeasurement(name: string, category?: string, argumentName?: string): any;
}

/**
 * Diagnostic message without origin information
 */
interface DiagnosticWithoutOrigin {
  /** The diagnostic message */
  message: string;
  /** Optional hints for fixing the issue */
  hints?: Array<string>;
  /** Optional documentation URL for more information */
  documentationURL?: string;
}

Behavior

Development Mode

  • Returns null (no compression applied)
  • Allows faster build times during development

Production Mode

  • Creates Brotli compressed stream using maximum quality settings
  • Uses zlib.constants.BROTLI_MAX_QUALITY for optimal compression
  • Returns compressed stream with type: 'br' content encoding
  • Generates .br files alongside original files

Compression Settings

  • Quality: Maximum (zlib.constants.BROTLI_MAX_QUALITY)
  • Algorithm: Brotli via Node.js zlib.createBrotliCompress()
  • Content Type: 'br' (standard Brotli encoding identifier)

Integration

This plugin works in conjunction with:

  • Parcel's plugin system: Automatic loading and execution
  • Other compressors: Can be used alongside gzip compression
  • Build pipeline: Integrates with Parcel's asset processing workflow
  • File types: Compresses JavaScript, CSS, HTML, SVG, and source maps

Error Handling

The plugin handles errors through Parcel's standard plugin error reporting system. Common scenarios:

  • Compression failures: Logged through the provided logger instance
  • Stream errors: Propagated through the returned stream
  • Configuration issues: Handled by Parcel's plugin loader