esbuild-compress

2.2.0 verified Fri May 01 auth: no javascript

esbuild-compress is a plugin for esbuild that compresses embedded data at build time to reduce bundle size, with runtime decompression. Current stable version is 2.2.0. It supports various compression algorithms via configurable compressors, including lazy (async) decompression. Key differentiators: designed specifically for esbuild, supports both sync and async decompression, and works with multiple data formats (JSON, text, etc.). Released under MIT license.

Common errors

error Error: Cannot find module 'esbuild-compress' ↓

cause Package not installed or not in node_modules.

fix

Run npm install esbuild-compress --save-dev

error TypeError: esbuildCompress is not a function ↓

cause Using named import instead of default import.

fix

Change to 'import esbuildCompress from "esbuild-compress"'

error error: [plugin esbuild-compress] Cannot find module 'iltorb' ↓

cause Missing optional dependency for brotli compression.

fix

Install iltorb if needed: npm install iltorb

error SyntaxError: Cannot use import statement outside a module ↓

cause Using ESM syntax in a CommonJS project without type: module.

fix

Add "type": "module" to package.json or use .mjs extension.

Warnings

breaking Requires esbuild >=0.17.0 due to plugin API changes. ↓

fix Upgrade esbuild to version 0.17.0 or higher.

gotcha The 'lazy' option makes decompression async; importing without await will return a Promise. ↓

fix Use await when importing lazy-compressed modules: const data = await import('./file.txt') (if using dynamic imports) or access the default export and await if using static imports with lazy loader.

breaking Version 2.x dropped support for CommonJS (require). ↓

fix Switch to ESM imports (import).

Install

npm install esbuild-compress

yarn add esbuild-compress

pnpm add esbuild-compress

Imports

default

wrong

const esbuildCompress = require('esbuild-compress')

correct

import esbuildCompress from 'esbuild-compress'

ESM-only package; CommonJS require is not supported.

esbuildCompress

wrong

import { esbuildCompress } from 'esbuild-compress'

correct

import esbuildCompress from 'esbuild-compress'

Package uses default export only; named import will yield undefined.

Plugin type (TypeScript)

wrong

import { Plugin } from 'esbuild-compress'

correct

import type { Plugin } from 'esbuild'; import esbuildCompress from 'esbuild-compress'

Plugin type is from esbuild, not from esbuild-compress.

Quickstart

Shows basic usage of esbuild-compress plugin with two compressors: one for JSON files (sync) and one for text files (lazy/async).

import { build } from 'esbuild';
import esbuildCompress from 'esbuild-compress';

await build({
  entryPoints: ['input.js'],
  outfile: 'output.js',
  bundle: true,
  plugins: [
    esbuildCompress({
      compressors: [
        { filter: /\.json$/, loader: 'json' },
        { filter: /\.txt$/, lazy: true, loader: 'text' },
      ],
    }),
  ],
});