npm package: @lxgicstudios/blurhash-gen
Description: Generate BlurHash-style base64 placeholder strings for images. Output as CSS background, data-URI, or raw hash with zero dependencies.
Author: LXGIC Studios
Latest version: 1.0.0

# @lxgicstudios/blurhash-gen

[![npm version](https://img.shields.io/npm/v/@lxgicstudios/blurhash-gen)](https://www.npmjs.com/package/@lxgicstudios/blurhash-gen)
[![license](https://img.shields.io/npm/l/@lxgicstudios/blurhash-gen)](https://github.com/lxgicstudios/blurhash-gen/blob/main/LICENSE)
[![node](https://img.shields.io/node/v/@lxgicstudios/blurhash-gen)](https://nodejs.org)
[![zero deps](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/@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

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

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

## Usage

```bash
# 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)
```css
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](https://lxgicstudios.com)