Appwrite Storage

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

export const imageConfig = {
  provider: 'appwrite',
  providers: {
    appwrite: appwriteProvider({
      "baseURL": "https://fra.cloud.appwrite.io/v1/storage",
      "projectId": "your-project-id"
    })
  }
} satisfies ImageConfig;

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

Image source

Use a full HTTP(S) Storage file URL ending in /view or /preview, or a file path relative to baseURL. The provider changes /view to /preview and preserves existing query parameters and fragments. Explicit modifiers replace matching query parameters.

/buckets/photos/files/hero/view

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="/buckets/photos/files/hero/view"
  alt="Sample image" width={800} height={500}
  modifiers={{
  "quality": 80,
  "format": "webp",
  "gravity": "center"
}}
/>

Provider options

baseURL

Storage URL prefix for relative paths. Full source URLs keep their own host and path.

projectId

Fallback project ID when the source URL has no project query 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

Width, height and quality use Appwrite query parameters. Format maps to output and supports jpeg/jpg, png, gif, webp, avif and heic; JPEG is sent as jpg. Native preview modifiers such as gravity, borderWidth, borderColor, borderRadius, opacity, rotation and background pass through. Generic fit values throw; use gravity for crop positioning. Generic blur and position 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

• A non-empty project query parameter is required. The source project wins over the projectId fallback; an explicit project modifier wins over both. Project IDs identify the project and do not grant file access.
• Use publicly readable files. Existing token query parameters are retained, but the provider does not create sessions, tokens or API keys, or change Storage permissions.
• Width and height must be integers from 0 to 4000. The provider validates source query dimensions and every responsive candidate, and throws for invalid or excessive dimensions instead of silently clamping them. Keep both dimensions within the limit at every density.
• Appwrite Cloud transformations require a paid plan and are unavailable on Free. Self-hosted deployments need working preview transformations and support for the requested output format. Source files must meet the deployment's preview type and size limits.
• Appwrite accepts quality values from 0 to 100; the shared image helpers normalize explicit quality inputs to 1–100. Color parameters use hexadecimal values without a leading #. The provider generates URLs; Appwrite performs the transformations.

Full Storage URL without baseURL

import { createImage } from '@desource/image';
import { appwriteProvider } from '@desource/image/providers/appwrite';

const image = createImage({
  provider: 'appwrite',
  providers: { appwrite: appwriteProvider() }
});

const picture = image.getPicture({
  src: 'https://fra.cloud.appwrite.io/v1/storage/buckets/photos/files/hero/view?project=your-project-id',
  alt: 'Mountain lake',
  width: 800,
  height: 500,
  densities: [1, 2],
  formats: ['avif', 'webp'],
  fallbackFormat: 'jpeg'
});