svelte-imgproxy

Small Svelte 5 image component + helpers for imgproxy.

pnpm add @sandquist-group/svelte-imgproxy

Requires Svelte 5 and Node.js 20 or newer.

Designed for a setup like:

Svelte app -> https://images.example.com -> imgproxy -> private object storage

The default URL shape preserves aspect ratio and fits within width:

https://images.example.com/unsafe/rs:fit:640:0/plain/blog/hero.jpg

unsafe is the default imgproxy signature segment. Use a signed imgproxy endpoint and configure signature when the endpoint is exposed publicly.

Install locally

pnpm add ../svelte-imgproxy

For the published package, install @sandquist-group/svelte-imgproxy.

Configure once

In your app entry/layout, configure the singleton:

import { configureImgproxy } from 'svelte-imgproxy';

configureImgproxy({
  baseUrl: 'https://images.example.com',
  basePath: 'blog',
  widths: [320, 640, 960, 1280, 1920],
  sizes: '(max-width: 1280px) 100vw, 1280px'
});

Project-wide SvelteKit configuration (recommended)

Put an ImgproxyProvider in the root layout. Every nested Image inherits the configuration, so components need only receive their image key. Unlike a module-level singleton, this also stays isolated per SSR request.

<!-- src/routes/+layout.svelte -->
<script lang="ts">
  import { ImgproxyProvider } from 'svelte-imgproxy';
  import { PUBLIC_IMGPROXY_URL } from '$env/static/public';

  let { children } = $props();
</script>

<ImgproxyProvider
  config={{
    baseUrl: PUBLIC_IMGPROXY_URL,
    basePath: 'blog',
    widths: [320, 640, 960, 1280, 1920]
  }}
>
  {@render children()}
</ImgproxyProvider>

Use configureImgproxy(...) only for a static, app-wide configuration. It is module-level state: it may be called from any eagerly imported module, but it must run before Image renders and must never be changed per server request.

Use the component

<script lang="ts">
  import { Image } from 'svelte-imgproxy';
</script>

<Image
  image="hero.jpg"
  alt="Hero"
  class="hero-image"
/>

Image is the primary ergonomic export. ImgproxyImage and ImgOptim remain available as aliases.

With basePath: 'blog', image="hero.jpg" resolves to object key:

blog/hero.jpg

Per-image base path and opt-out

<Image basePath="portfolio" image="headshot.jpg" alt="Headshot" />

To use an image without the configured base path:

<Image image="shared/banner.jpg" useBasePath={false} alt="Banner" />

Full object key

Use objectKey when you do not want the configured base path added:

<ImgproxyImage objectKey="customer-x/banner.jpg" alt="Banner" />

Dynamic URL/key

Use url for dynamic values:

<ImgproxyImage url={post.imageKey} alt={post.title} />

If url is relative and a base path is configured, the base path is applied unless it already starts with that base path. Set useBasePath={false} to bypass it.

Custom widths

<ImgproxyImage
  image="gallery/photo.jpg"
  alt="Gallery photo"
  widths={[400, 800, 1200, 1600]}
  sizes="(max-width: 900px) 100vw, 900px"
/>

Rest props and classes

Most normal <img> props are forwarded:

<ImgproxyImage
  image="logo.png"
  alt="Logo"
  class="logo"
  style="height: auto; width: 12rem;"
  fetchpriority="high"
/>

loading defaults to lazy; decoding defaults to async.

SvelteKit / SSR configuration

configureImgproxy(...) is convenient for a browser-only app or a deployment with one shared image endpoint. In a multi-tenant SvelteKit app, avoid changing that module-level configuration during a request: pass the configuration to the component instead.

<Image
  image="hero.jpg"
  alt="Hero"
  config={{ baseUrl: 'https://images.example.com', basePath: tenant.slug }}
/>

Helper-only usage

import { buildImgproxyUrl, configureImgproxy } from 'svelte-imgproxy';

configureImgproxy({
  baseUrl: 'https://images.example.com',
  basePath: 'blog'
});

const url = buildImgproxyUrl({
  source: 'blog/hero.jpg',
  width: 960
});

API exports

• Image (primary component export)
• ImgproxyProvider (project-wide configuration)
• ImgproxyImage
• ImgOptim alias
• configureImgproxy(config)
• getImgproxyConfig()
• resetImgproxyConfig()
• buildImgproxyUrl(options)
• buildImgproxySrcset(options)
• resolveImgproxySource(input)
• DEFAULT_WIDTHS
• DEFAULT_SIZES

Developing

pnpm install
pnpm run dev
pnpm run check
pnpm run build

This repo was created from the official Svelte library template via sv create --template library.