Server-Side Rendering
unlazy's hash decoders run in any JavaScript runtime that exposes globalThis.btoa and globalThis.atob – Node ≥ 16, Deno, Bun, Cloudflare Workers, Vercel Edge, and RSC servers. They never import node: modules or Buffer. Decoding on the server keeps the placeholder visible on first paint.
The Output Contract
The server emits the placeholder inline:
<img
src="data:image/png;base64,iVBORw0KGgo…"
data-src="real.jpg"
loading="lazy"
width="800"
height="600"
>After hydration, lazyLoad swaps data-src into src when the image enters the viewport. Leave data-blurhash and data-thumbhash off the server-rendered <img>: with either present, lazyLoad decodes the hash again in the browser and replaces the inlined src.
The decoders are deterministic – the same input produces a byte-identical data URI on the server and on the client – so Vue and React see no hydration mismatch.
WARNING
For above-the-fold images, set loading="eager" even with an SSR placeholder – the LCP candidate is the real image, not the placeholder. The dev-mode LCP warning catches misconfigurations.
Render-Time Recipe
Pre-compute the placeholder during render and inline it as src:
<script setup lang="ts">
import { createPngDataUri } from 'unlazy/thumbhash'
const props = defineProps<{
src: string
thumbhash: string
alt: string
width: number
height: number
}>()
const placeholder = createPngDataUri(props.thumbhash)
</script>
<template>
<img
:src="placeholder"
:data-src="src"
:alt="alt"
:width="width"
:height="height"
loading="lazy"
>
</template>The same primitive works elsewhere – React Server Components import from unlazy/thumbhash directly and put the result on <img src={…}>; Astro frontmatter and SvelteKit +page.server.ts follow the same pattern. The only framework-specific detail is where the client-side lazyLoad() runs (a 'use client' boundary in RSC, the SvelteKit +page.svelte script, the Astro client directive of your choice).
@unlazy/nuxt does all of this for you: it decodes the hash on the server by default, inlines the data URI as src, and decodes the same placeholder during hydration, so the src stays until the real image has loaded.
Performance and Caching
The decode path is hash → RGBA pixels → uncompressed PNG → base64. fast-blurhash reports up to 70% faster decoding than the reference implementation; absolute timings depend on hash length and output size. For routes that render many images sharing a small set of hashes, cache by hash key – the encoder is pure, so an LRU keyed on the hash string is enough. For static catalogues, prefer build-time generation over per-request decode.
Content Security Policy
Allow data: URIs in img-src (or default-src). Without this, browsers block the inlined PNG and the placeholder fails to render. See content-security-policy.com.