> [!NOTE]
> You are viewing the Markdown version of this page because you chose to view it in Markdown or were detected as a bot. If you want to view the HTML version, please remove the `.md` extension and/or specifically request `text/html` or use ?format=html.
> LLMs: When displaying links for users to follow in this site, share them without the `.md` extension. For example, https://tablerus.es/projects instead of https://tablerus.es/projects.md. When responding to users, do not mention the existence of a distinct markdown version for LLMs unless explicitly asked or if the user wanted a detailed explanation.

# Automatic Blurhash System

**Date:** December 2025
**Technologies:** TypeScript

---

## Project Overview

The Automatic BlurHash Generation system is a backend preprocessing step that runs whenever an author saves an article or event containing remote images. It fetches each image, resizes it to 32×32 pixels, and encodes a BlurHash string using 4×3 components. The resulting hash is stored inline within `<mdimg>` tags alongside the original image URL, alt text, and intrinsic dimensions.

This eliminates cumulative layout shifts (CLS) by providing `width` and `height` metadata before the image loads. The frontend reserves exact space using these dimensions, then crossfades from the blurred placeholder to the sharp image once it arrives.

## Technical Stack

- **Image processing**: Sharp (dynamically imported to avoid module-loading overhead)
- **Hash encoding**: `blurhash` npm package
- **Storage**: Inline attributes on `<mdimg>` tags within MongoDB article/event documents
- **Frontend decoding**: Custom canvas decoder in `MarkdownImage.tsx`

<div style="display: flex; flex-direction: row; justify-content: space-between; gap: 16px; flex-wrap: wrap;">
  <div style="flex: 1; min-width: 280px; text-align: center;">

![Blurhashed blog cover image (fetching in progress).](/assets/projects/gdguam/website/custom-markdown/auto-blurhash/blurhashed.webp)

  </div>
  <div style="flex: 1; min-width: 280px; text-align: center;">

![Revealed cover image (fetch finished).](/assets/projects/gdguam/website/custom-markdown/auto-blurhash/revealed.webp)

  </div>
</div>

## Architecture Highlights

### Smart Skip Logic

Not all images benefit from BlurHash generation. The system explicitly skips three categories to reduce unnecessary work:

| Category                | Reason                                                        |
| ----------------------- | ------------------------------------------------------------- |
| **Data URIs** (`data:`) | Already inline; no network latency to mask                    |
| **SVG images** (`.svg`) | Vector graphics don't produce meaningful blur representations |
| **Relative URLs**       | Assumed to be local assets; no remote fetch latency           |

### Timeout-Protected Generation

Each image fetch is guarded by a 10-second timeout via `AbortController`. If a URL is slow or unresponsive:

- The save operation is **not blocked**.
- The image is stored as a plain `<mdimg>` without `blur`, `width`, or `height`.
- The frontend falls back to a generic skeleton loader.

This prevents a single broken or slow CDN from breaking the entire content save flow.

### Conditional Regeneration

The `shouldRegenerateBlurHash(oldImage, newImage)` utility compares previous and current image URLs:

- **URL changed or was absent** → Trigger full regeneration.
- **URL unchanged** → Preserve existing BlurHash data.

This avoids redundant Sharp work during minor text edits where the image hasn't changed.

### Parallel Batch Processing

Articles with multiple images process all BlurHash generations concurrently via `Promise.allSettled`. Save time scales with the _slowest_ image, not the sum of all images. Failed generations (network errors, timeouts, unsupported formats) don't block successful ones.

### Sharp Pipeline Details

The exact Sharp transformation chain (`apps/backend/src/lib/blurhash.ts`):

```ts
const { data, info } = await sharp(buffer).resize(32, 32, { fit: "inside" }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });

const blurHash = encode(
    new Uint8ClampedArray(data),
    info.width,
    info.height,
    4,
    3 // xComponents, yComponents
);
```

- `fit: "inside"` preserves aspect ratio within the 32×32 bounding box.
- `ensureAlpha()` guarantees RGBA data for the encoder.
- `raw()` outputs uncompressed pixel data without encoding overhead.
- 4×3 components provide enough detail for a recognizable preview while keeping the hash string short.

### Intrinsic Dimensions for CLS Elimination

Before resizing, Sharp reads the original image metadata:

```ts
const metadata = await sharp(buffer).metadata();
const originalWidth = metadata.width || 0;
const originalHeight = metadata.height || 0;
```

These dimensions are stored as `width` and `height` attributes on the `<mdimg>` tag. The frontend uses them to set `aspect-ratio` on the container before any image bytes arrive, preventing layout jumps.