@lxgicstudios/blurhash-gen

Generate BlurHash-style base64 placeholder strings for images. Read image dimensions from headers, create tiny color-averaged placeholders. Output as CSS background, data-URI, or raw hash. Zero dependencies.

Install

# Run directly
npx @lxgicstudios/blurhash-gen photo.jpg

# Or install globally
npm i -g @lxgicstudios/blurhash-gen

Usage

# Generate CSS placeholder for a single image
blurhash-gen hero.jpg

# Process all images in a directory
blurhash-gen --batch ./images

# Output as data-URI for img src placeholder
blurhash-gen --format data-uri photo.png

# Raw base64 hash
blurhash-gen --format raw banner.webp

# JSON output for build tools
blurhash-gen --json --batch ./public/images

# Custom placeholder grid size
blurhash-gen --width 6 --height 4 photo.jpg

Features

• Multiple output formats: CSS linear-gradient, SVG data-URI, or raw base64
• Image header parsing reads dimensions from PNG, JPEG, GIF, WebP, and BMP without decoding
• Batch processing scans directories recursively for all image files
• Color sampling extracts average color from image data
• Gradient generation creates smooth color variations for realistic blur effect
• SVG data-URI output includes Gaussian blur filter for smooth results
• Configurable grid size controls placeholder detail level
• JSON output for integration with build tools and frameworks
• Zero external dependencies (pure Node.js builtins)

Output Formats

CSS (default)

background: linear-gradient(180deg, rgb(142,158,172) 0%, rgb(138,155,170) 50%, rgb(134,152,168) 100%);
background-size: cover;
aspect-ratio: 1920 / 1080;

Data URI

A tiny SVG with colored rectangles and a Gaussian blur filter, encoded as base64. Drop it into an img tag's src as a loading placeholder.

Raw

Base64-encoded color grid data. Compact format for storing in databases or APIs.

Supported Formats

| Format | Dimensions | Color Sampling | |--------|-----------|----------------| | PNG | ✓ | ✓ | | JPEG | ✓ | ✓ | | GIF | ✓ | ✓ | | WebP | ✓ | ✓ | | BMP | ✓ | ✓ |

Options

| Option | Description | Default | |--------|-------------|---------| | --batch <dir> | Process all images in a directory | - | | --format <type> | Output format: css, data-uri, or raw | css | | --width <n> | Placeholder grid width | 4 | | --height <n> | Placeholder grid height | 3 | | --json | Output results as JSON | false | | --help | Show help message | - |

Example Output

 blurhash-gen v1.0.0

Processing 3 image(s)...

  ✓ images/hero.jpg
    Dimensions:  1920x1080  (JPEG, 245.2 KB)
    Avg color:   rgb(142, 158, 172)
    Format:      css
    Output:
      background: linear-gradient(180deg, rgb(142,158,172) 0%, ...);
      background-size: cover;
      aspect-ratio: 1920 / 1080;

 Done  3 placeholder(s) generated

License

MIT - LXGIC Studios