Contentstack

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 { contentstackProvider } from '@desource/image/providers/contentstack';

export const imageConfig = {
  provider: 'contentstack',
  providers: {
    contentstack: contentstackProvider({
      "environment": "production"
    })
  }
} satisfies ImageConfig;

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

Image source

Use the full asset delivery URL from Contentstack, including its regional or custom hostname and complete asset path. Existing environment, branch, query parameters, and fragments are retained. Explicit modifiers replace matching query parameters.

https://eu-images.contentstack.com/v3/assets/stack-api-key/asset-uid/file-uid/photo.jpg?environment=production

Usage

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

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

  setDsImageConfig(imageConfig);
</script>

<DsImage
  src="https://eu-images.contentstack.com/v3/assets/stack-api-key/asset-uid/file-uid/photo.jpg?environment=production"
  alt="Sample image" width={800} height={500}
  modifiers={{
  "quality": 80,
  "format": "webp",
  "fit": "cover"
}}
/>

Provider options

baseURL

Optional delivery origin and asset prefix for relative sources. Absolute URLs keep their own host.

environment

Fallback publishing environment when the source URL has no environment parameter.

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, quality, jpeg/jpg, png, gif, webp, and avif. JPEG is sent as jpg. Fit cover maps to crop for exact dimensions; contain maps to bounds to preserve aspect ratio within the requested box. Native crop and bounds fit values are also accepted. Other fit values and formats throw. Native crop expressions such as crop: "100,80,x10,y20" pass through unchanged.

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

• Publish the asset to the requested environment. An environment must be present in the source URL, provider configuration, or modifiers; missing or empty environments throw. The source environment wins over the configured fallback, and an explicit environment modifier wins over both.
• Fit requires both width and height, from modifiers or source URL query parameters; missing dimensions throw. Bounds can return a smaller dimension on one axis; use cover for exact card or hero dimensions. Contentstack native fit=cover can return a larger dimension and is not forwarded for core cover.
• Use explicit formats for picture sources. An explicit format removes any auto parameter because native auto negotiation can override it. Without an explicit format, existing or native auto parameters are preserved. The adapter does not support format=auto, pjpg, webpll, or webply.
• Native controls such as crop, trim, disable, and blur can be passed in modifiers. Crops and disable: "upscale" can change output dimensions; keep responsive descriptors consistent with the resulting image.
• Server-side probes should send an Accept header for the requested WebP or AVIF format. Verify response Content-Type and decoded dimensions on your delivery endpoint.

Relative asset paths

contentstackProvider({
  baseURL: 'https://eu-images.contentstack.com/v3/assets/your-stack',
  environment: 'production'
});
// src: 'your-asset/your-file/photo.jpg'