nuxt-bunny-image-statamic

nuxt-bunny-image-statamic

Nuxt 4 module for rendering Statamic image objects through a Bunny.net Optimizer pull zone.

Combines the ideas of @teamnovu/vue-cloudinary-image-statamic and @teamnovu/vue-bunny-image:

• Handles Statamic image objects (permalink/url, width, height)
• Auto-applies the alt attribute
• Auto-applies the Statamic focal point (focus / focus_css) as a Bunny crop
• Responsive srcset from a dense width ladder (~20% steps), capped at the image's intrinsic width
• sizes="auto" on lazy images — supporting browsers pick the variant from the real rendered width
• Blur-up placeholder, native lazy loading, layout-shift prevention

Install

pnpm add nuxt-bunny-image-statamic

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-bunny-image-statamic'],
})

# .env — just the pull-zone name, becomes https://your-zone.b-cdn.net
BUNNY_PULL_ZONE_NAME=your-zone

Instead of the zone name you can set a full URL — as BUNNY_BASE_URL=https://your-zone.b-cdn.net in .env, or in nuxt.config.ts:

bunnyImage: {
  baseUrl: 'https://your-zone.b-cdn.net',
},

Resolution order: a full https://… base URL (option or BUNNY_BASE_URL) wins; otherwise the pull-zone name (option or BUNNY_PULL_ZONE_NAME) is merged with the base-URL domain (BUNNY_BASE_URL as bare domain, default b-cdn.net). Module options win over env vars.

Usage

<!-- hand the Statamic image object straight in -->
<AppImage :src="entry.image" />

<!-- square avatar cropped around the focal point -->
<AppImage :src="entry.image" :aspect-ratio="1" sizes="4rem" />

Make sure your Statamic API output includes permalink (or url), width, height, alt, and focus (or focus_css).

Module options (bunnyImage)

Component props

src (Statamic image object or path, required), alt, focus, width, height, aspect-ratio, sizes (default 100vw), loading (default lazy), quality, sharpen, blur, crop, crop-gravity, flip, flop, brightness, saturation, hue, contrast, optimization, sepia, placeholder (default true), placeholder-width (default 300), placeholder-quality (default 30).

See the Bunny Optimizer docs for what each transform does.

sizes and lazy loading

On lazy images (the default) the rendered attribute is sizes="auto, <your value>": browsers supporting sizes="auto" pick the srcset candidate from the image's real laid-out width; others fall back to your value (default 100vw). Eager images (loading="eager") can't use auto — the request is made before layout — so give above-the-fold images an accurate explicit sizes (e.g. sizes="(min-width: 768px) 50vw, 100vw").

Composable

const { buildUrl, buildSrcSet } = useAppImage()
const ogImage = buildUrl('/img/hero.jpg', { width: 1200, aspectRatio: '1200:630' })

Development

pnpm install
pnpm dev:prepare
pnpm dev        # playground
pnpm test