imgproxy

Setup

Install the framework package and the core package for the provider import:

npm install @desource/image @desource/image-svelte

Save this as image.config.ts beside your example component. Replace sample domains and identifiers with your own.

import type { ImageConfig } from '@desource/image';
import { imgproxyProvider } from '@desource/image/providers/imgproxy';

export const imageConfig = {
  provider: 'imgproxy',
  providers: {
    imgproxy: imgproxyProvider({
      "baseURL": "https://imgproxy.example.com"
    })
  }
} satisfies ImageConfig;

Registering this provider makes it the default for the configured components. To mix services, register each provider and set provider="imgproxy" on the image that should use this one.

Image source

Use the absolute source URL that imgproxy can fetch. The adapter encodes it as URL-safe Base64.

https://images.example.com/photo.jpg

Usage

The example uses the shared configuration above and the Svelte image component.

<script lang="ts">
  import { Image, setImageConfig } from '@desource/image-svelte';
  import { imageConfig } from './image.config';

  setImageConfig(imageConfig);
</script>

<Image
  src="https://images.example.com/photo.jpg"
  alt="Sample image" width={800} height={500}
  modifiers={{
  "quality": 80,
  "format": "webp",
  "fit": "cover"
}}
/>

Provider options

baseURL

The imgproxy server origin.

key

Hex-encoded signing key. Keep this in server-only configuration.

salt

Hex-encoded signing salt. Keep this in server-only configuration.

Pass shared defaults such as screens, domains, aliases and presets to the image configuration. Pass provider-specific defaults as modifiers in the provider factory.

Modifiers

Supports width, height, fit, format, quality, resizingType, gravity, crop objects, dpr, enlarge, extend, rotate, blur, sharpen and metadata controls.

Set dimensions on the component and pass service-specific operations through modifiers, as shown above. See the provider source for exact mappings and the service documentation for accepted values.

Provider notes

• Without both key and salt, the URL uses the unsafe signature segment. The server must permit unsigned URLs for the basic browser example.
• For a signed production endpoint, generate URLs on the server. Never put key or salt in browser code or serialize them to a page.
• Signing values must be non-empty, even-length hex strings. Rotate is rounded down to a multiple of 90 degrees.
• Fit cover selects fill, contain selects fit plus extension, and fill selects force when both dimensions are present.

Generate a signed URL on the server

// Server-only module; do not import it into browser code.
import { createImage } from '@desource/image';
import { imgproxyProvider } from '@desource/image/providers/imgproxy';

const image = createImage({
  provider: 'imgproxy',
  providers: {
    imgproxy: imgproxyProvider({
      baseURL: 'https://imgproxy.example.com',
      key: process.env.IMGPROXY_KEY,
      salt: process.env.IMGPROXY_SALT
    })
  }
});

export const imageURL = image('https://images.example.com/photo.jpg', {
  width: 800, format: 'webp', quality: 80
});
// Send only imageURL to the browser, then render it with provider: 'none'.