Filestack

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

export const imageConfig = {
  provider: 'filestack',
  providers: {
    filestack: filestackProvider()
  }
} satisfies ImageConfig;

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

Image source

Use a file handle, /handle, or an untransformed file URL on cdn.filestackcontent.com or your configured CDN origin. External HTTP(S) URLs and src://alias/path sources require apiKey. Their full source, including embedded query parameters, is encoded as UTF-8 URL-safe Base64 with padding after b64:// in the processing URL. Existing transformed or signed CDN URLs, and CDN URLs with queries or fragments, are rejected; pass the original source instead.

YourFilestackHandle

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="YourFilestackHandle"
  alt="Sample image" width={800} height={600}
  modifiers={{
  "fit": "cover",
  "quality": 80,
  "format": "webp"
}}
/>

Provider options

baseURL

Optional HTTP(S) CDN origin. Defaults to https://cdn.filestackcontent.com. Paths, queries, credentials and fragments are not supported.

apiKey

Public application API key, required for external HTTP(S) sources and src:// storage aliases.

signURL

Optional synchronous server-only callback. Receives each final transformation URL and returns its authorized URL.

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

Width and height become resize parameters. Fit maps cover to crop, contain to clip, fill to scale, and inside or scale-down to max; native clip, crop, scale and max are also accepted. Crop and scale require both dimensions. Format and quality form an output task after resize. Formats include jpg/jpeg, png, webp and avif; JPEG is sent as jpg. Other formats, including auto, auto_image, pjpg and svg, are rejected. Outside fit is unsupported. Other modifiers, including position, background and blur, are omitted.

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

• Dimensions must be integers from 1 to 10000. Every responsive candidate is validated; keep both dimensions within that range at every density. Quality accepts integers from 1 to 100.
• Clip preserves the source aspect ratio inside the requested bounds, and max also prevents upscaling. These modes can return smaller dimensions than requested. Use crop with both dimensions when the output must fill a responsive image box.
• External images must be reachable by Filestack. Storage aliases must be configured for the application identified by apiKey. The public API key identifies the application; it is not a signing secret.
• Security-enabled applications need a Filestack security policy with the required read and convert permissions. A policy restricts sources, calls and expiry; it does not bind the signature to transformation dimensions or an exact task chain. Restricting delivery to specific derivatives requires an application proxy or custom delivery layer outside this provider.
• Keep signing secrets and signURL in server code. The callback runs after task serialization for every responsive, picture and placeholder URL. Generate a fresh policy and signature when authorization expires; the provider does not sign or refresh policies.
• Send the finalized image attributes from the server to the browser. Render those attributes directly, or use the none provider for a finalized URL. Do not pass signed URLs back through the Filestack provider.
• The provider builds URLs; Filestack performs the transformations. Format availability and transformation permissions depend on your Filestack application.

External images and storage aliases

import { createImage } from '@desource/image';
import { filestackProvider } from '@desource/image/providers/filestack';

const image = createImage({
  provider: 'filestack',
  providers: {
    filestack: filestackProvider({ apiKey: 'your-public-api-key' })
  }
});

const remote = image('https://images.example.com/hero.jpg?version=2&token=a%2Bb', {
  width: 800,
  height: 600,
  fit: 'cover',
  format: 'webp'
});

const stored = image('src://product-images/hero.jpg', {
  width: 800,
  height: 600,
  fit: 'cover',
  format: 'webp'
});

Server-side authorization

// Keep this configuration in a server-only module.
import { createImage } from '@desource/image';
import { filestackProvider } from '@desource/image/providers/filestack';
// Your application implements this helper with Filestack policy signing.
// https://www.filestack.com/docs/security/policies/
import { authorizeFilestackURL } from './filestack-signing.server';

const image = createImage({
  provider: 'filestack',
  providers: {
    filestack: filestackProvider({ signURL: authorizeFilestackURL })
  }
});

const picture = image.getPicture({
  src: 'YourFilestackHandle',
  alt: 'Mountain lake',
  width: 800,
  height: 600,
  fit: 'cover',
  densities: [1, 2],
  formats: ['avif', 'webp'],
  fallbackFormat: 'jpeg'
});

// Render picture.sources and picture.img directly.
// Send only these finalized attributes to the browser.