DeSource Image

https://github.com/desource-labs/image
Admin
DeSource Image provides high-quality image optimization with a responsive, provider-first, and...
Tokens:108,047
Snippets:467
Trust Score:7.5
License:MIT
Update:2 days ago
Show doc for...
Tokens:
Raw
### Install and verify development setup

Source: https://github.com/desource-labs/image/blob/main/CONTRIBUTING.md

Run these commands after cloning the repository to install dependencies, build all packages, run type checks, and execute unit tests. Requires Node.js 22.18+ and pnpm 10.33+.

```sh
pnpm install
pnpm build:all
pnpm typecheck
pnpm test:unit
```

--------------------------------

### Start the demo site

Source: https://github.com/desource-labs/image/blob/main/README.md

Prepare the development environment and start the demo site.

```sh
pnpm dev:prepare
pnpm dev:demo
```

--------------------------------

### Use DsImage and DsPicture components

Source: https://github.com/desource-labs/image/blob/main/packages/react/README.md

Quick start example showing DsImage and DsPicture usage. Both render native elements; DsImage forwards refs to the <img> and DsPicture forwards refs to the <picture>.

```tsx
import { DsImage, DsPicture } from '@desource/image-react';

export function Gallery() {
  return (
    <>
      <DsImage
        src="/img/hero.jpg"
        alt="Mountain lake at sunrise"
        width={1600}
        height={1000}
        sizes="100vw md:760px"
        format="webp"
        quality={76}
        placeholder
        preload={{ fetchPriority: 'high' }}
        className="hero"
      />

      <DsPicture
        src="/img/card.jpg"
        alt="Cabin under the stars"
        width={960}
        height={640}
        formats={['avif', 'webp']}
        fallbackFormat="jpg"
        imgAttrs={{ className: 'card-image' }}
      />
    </>
  );
}
```

--------------------------------

### Install SvelteKit package

Source: https://github.com/desource-labs/image/blob/main/README.md

Install the SvelteKit package for the Desource image component.

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

--------------------------------

### Install React package

Source: https://github.com/desource-labs/image/blob/main/README.md

Install the React package for the Desource image component.

```sh
npm install @desource/image-react
```

--------------------------------

### Install dependencies and run build, typecheck, tests, and package validation

Source: https://github.com/desource-labs/image/blob/main/README.md

Run these commands in order to install dependencies, build the project, run type checking, execute unit tests with coverage, run end-to-end tests, and validate packages.

```sh
pnpm install
pnpm build
pnpm typecheck
pnpm test:unit:coverage
pnpm test:e2e
pnpm validate:packages
```

--------------------------------

### Configure Cloudinary provider with imageConfig

Source: https://github.com/desource-labs/image/blob/main/README.md

Optional configuration for DeSource Image. With no explicit provider, 'auto' uses deployment detection and falls back to IPX. This example sets provider to 'cloudinary' with quality, screens, densities, aliases, domains, patterns, presets, and a memoized provider setup.

```TypeScript
import { cloudinaryProvider } from '@desource/image/providers/cloudinary';

export const imageConfig = {
  provider: 'cloudinary',
  quality: 76,
  screens: {
    sm: 640,
    md: 768,
    lg: 1024,
    xl: 1280
  },
  densities: [1, 2],
  aliases: {
    media: 'https://assets.example.com'
  },
  domains: ['assets.example.com'],
  localPatterns: [{ pathname: '/img/**' }],
  remotePatterns: [{ protocol: 'https', hostname: '*.example.com', pathname: '/media/**' }],
  presets: {
    card: {
      width: 960,
      height: 640,
      sizes: '100vw md:480px',
      format: 'webp'
    }
  },
  providers: {
    cloudinary: cloudinaryProvider({ cloudName: 'demo' })
  },
  onInvalidSource: 'warn'
} as const;
```

--------------------------------

### Install Angular package

Source: https://github.com/desource-labs/image/blob/main/README.md

Install the Angular package for the Desource image component.

```sh
npm install @desource/image-angular
```

--------------------------------

### Install ipx for local transformations

Source: https://github.com/desource-labs/image/blob/main/packages/react/README.md

Install ipx only when the app serves local /_ipx transformations itself. ipx is an optional peer dependency; hosted providers do not need it.

```sh
npm install ipx
```

--------------------------------

### Install core TypeScript package

Source: https://github.com/desource-labs/image/blob/main/README.md

Install the core TypeScript package for the Desource image library.

```sh
npm install @desource/image
```

--------------------------------

### Quick start with createImage and callable helper

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Create an image instance with quality, screens, and presets. Use the callable helper to generate URLs, attributes, picture data, and preset shortcuts. The helper also exposes getImage, getSizes, getMeta, getPreloadLink, and one shortcut per configured preset.

```ts
import { createImage } from '@desource/image';

const image = createImage({
  quality: 76,
  screens: {
    sm: 640,
    md: 768,
    lg: 1024
  },
  presets: {
    avatar: {
      width: 96,
      height: 96,
      fit: 'cover',
      format: 'webp'
    }
  }
});

const url = image('/img/hero.jpg', {
  width: 800,
  format: 'webp'
});

const attrs = image.getAttrs({
  src: '/img/hero.jpg',
  alt: 'Mountain lake',
  width: 1600,
  height: 1000,
  sizes: '100vw md:760px',
  placeholder: true
});

const picture = image.getPicture({
  src: '/img/hero.jpg',
  alt: 'Mountain lake',
  width: 1600,
  height: 1000,
  formats: ['avif', 'webp'],
  fallbackFormat: 'jpg'
});

const avatarUrl = image.avatar('/people/ada.jpg');
```

--------------------------------

### Configure providers and presets with setDsImageConfig

Source: https://github.com/desource-labs/image/blob/main/packages/svelte/README.md

Register built-in or custom providers and define presets in the shared configuration. The example sets the cloudinary provider with a cloud name and an avatar preset for resizing.

```svelte
<script lang="ts">
  import { cloudinaryProvider } from '@desource/image/providers/cloudinary';
  import { setDsImageConfig } from '@desource/image-svelte';

  setDsImageConfig({
    provider: 'cloudinary',
    providers: {
      cloudinary: cloudinaryProvider({ cloudName: 'demo' })
    },
    presets: {
      avatar: { width: 96, height: 96, fit: 'cover', quality: 80 }
    }
  });
</script>
```

--------------------------------

### Create IPX server hook with createDsImageHandle

Source: https://github.com/desource-labs/image/blob/main/packages/svelte/README.md

Install ipx as a production dependency and add a server hook to handle image optimization. All IPX adapters load the optimizer lazily and only handle requests under the configured path. Remote optimization is denied by default; add trusted domains or set allowAllDomains: true only for an intentionally public optimizer.

```ts
// src/hooks.server.ts
import { createDsImageHandle } from '@desource/image-svelte/server';

export const handle = createDsImageHandle({
  dirs: ['static'],
  domains: ['images.example.com'],
  maxAge: 60 * 60 * 24 * 30
});
```

--------------------------------

### Define and configure a custom provider with defineProvider and configureProvider

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Shows the provider contract: a provider receives a normalized source, merged options, and an image context, then returns a URL. The setup is memoized; per-config providerOptions[name] merge over configured defaults, and standard width/height/quality/format modifiers merge last. Set validateDomains: true when remote inputs must match configured domains or remotePatterns; set acceptsOpaqueSource: true only for asset-ID sources.

```TypeScript
import { configureProvider, defineProvider } from '@desource/image';

interface AcmeOptions {
  baseURL: string;
  token?: string;
}

const setup = defineProvider<AcmeOptions>({
  validateDomains: true,
  getImage(src, { modifiers, baseURL, token }, context) {
    const query = new URLSearchParams({
      src,
      width: String(modifiers.width ?? ''),
      quality: String(modifiers.quality ?? '')
    });

    if (token) query.set('token', token);

    return {
      url: `${baseURL}?${query}`,
      isOptimized: true
    };
  }
});

export const acmeProvider = configureProvider(
  setup,
  {
    baseURL: 'https://images.example.com/transform'
  },
  'acme'
);
```

--------------------------------

### defineProvider

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Defines a custom provider by specifying a setup function that receives a normalized source, merged options, and an image context, and returns a URL. The setup function can include options like validateDomains and acceptsOpaqueSource.

```APIDOC
## defineProvider

### Description
Defines a custom provider by specifying a setup function that receives a normalized source, merged options, and an image context, and returns a URL. The setup function can include options like validateDomains and acceptsOpaqueSource.

### Method
N/A (TypeScript function)

### Endpoint
N/A

### Parameters
#### Options
- **validateDomains** (boolean) - Optional - When true, remote inputs must match configured `domains` or `remotePatterns`.
- **acceptsOpaqueSource** (boolean) - Optional - Set to true only for providers whose source is an asset ID rather than a path or URL.

#### Setup Function Parameters
- **src** (string) - Required - The normalized source.
- **options** (object) - Required - Merged options including provider-specific options and standard modifiers.
  - **modifiers** (object) - Required - Standard width/height/quality/format modifiers.
  - **baseURL** (string) - Optional - Base URL for the provider.
  - **token** (string) - Optional - Token for authentication.
- **context** (object) - Required - Image context exposing resolved options and a memoized `$img` helper.

### Response
#### Success Response
- **url** (string) - The generated URL.
- **isOptimized** (boolean) - Whether the image is optimized.

### Request Example
```ts
import { configureProvider, defineProvider } from '@desource/image';

interface AcmeOptions {
  baseURL: string;
  token?: string;
}

const setup = defineProvider<AcmeOptions>({
  validateDomains: true,
  getImage(src, { modifiers, baseURL, token }, context) {
    const query = new URLSearchParams({
      src,
      width: String(modifiers.width ?? ''),
      quality: String(modifiers.quality ?? '')
    });

    if (token) query.set('token', token);

    return {
      url: `${baseURL}?${query}`,
      isOptimized: true
    };
  }
});

export const acmeProvider = configureProvider(
  setup,
  {
    baseURL: 'https://images.example.com/transform'
  },
  'acme'
);
```
```

--------------------------------

### Configure DsImageProvider with cloudinary

Source: https://github.com/desource-labs/image/blob/main/packages/react/README.md

Example of configuring the provider once using DsImageProvider. Configuration is optional; without it, the runtime detects Vercel, Netlify, or AWS Amplify and falls back to IPX.

```tsx
import { DsImageProvider } from '@desource/image-react';
import { cloudinaryProvider } from '@desource/image/providers/cloudinary';

export function App() {
  return (
    <DsImageProvider
      config={{
        provider: 'cloudinary',
        quality: 80,
        screens: { sm: 640, md: 768, lg: 1024 },
        domains: ['images.example.com'],
        providers: {
          cloudinary: cloudinaryProvider({ cloudName: 'demo' })
        },
        presets: {
          avatar: { width: 96, height: 96, fit: 'cover', format: 'webp' }
        }
      }}
    >
      <Gallery />
    </DsImageProvider>
  );
}
```

--------------------------------

### Import provider subpaths for application code

Source: https://github.com/desource-labs/image/blob/main/README.md

Prefer provider subpaths for application code to keep bundles small. This example imports the Cloudinary, Imgix, and Sanity providers individually.

```TypeScript
import { cloudinaryProvider } from '@desource/image/providers/cloudinary';
import { imgixProvider } from '@desource/image/providers/imgix';
import { sanityProvider } from '@desource/image/providers/sanity';
```

--------------------------------

### Run package demos and root SvelteKit app

Source: https://github.com/desource-labs/image/blob/main/CONTRIBUTING.md

Use these commands for focused development on a specific framework package or the root SvelteKit documentation app. The Angular, React, and Svelte demos are run via pnpm filters; the root demo is started with pnpm dev:demo.

```sh
pnpm --filter @desource/image-angular dev
pnpm --filter @desource/image-react dev
pnpm --filter @desource/image-svelte dev
pnpm dev:demo
```

--------------------------------

### IPX URL example

Source: https://github.com/desource-labs/image/blob/main/README.md

The IPX provider generates URLs like this. URL generation does not transform bytes; the application must expose an optimizer route when using local IPX URLs.

```text
/_ipx/w_800&f_webp&q_76/img/hero.jpg
```

--------------------------------

### configureProvider

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Configures a provider with default options and a name. The provider setup is memoized, and per-config providerOptions are merged over configured defaults.

```APIDOC
## configureProvider

### Description
Configures a provider with default options and a name. The provider setup is memoized, and per-config providerOptions are merged over configured defaults.

### Method
N/A (TypeScript function)

### Endpoint
N/A

### Parameters
- **setup** (object) - Required - The provider setup object returned by `defineProvider`.
- **defaultOptions** (object) - Required - Default options for the provider.
- **name** (string) - Required - The provider name.

### Response
#### Success Response
- **provider** (object) - The configured provider.

### Request Example
```ts
import { configureProvider, defineProvider } from '@desource/image';

interface AcmeOptions {
  baseURL: string;
  token?: string;
}

const setup = defineProvider<AcmeOptions>({
  validateDomains: true,
  getImage(src, { modifiers, baseURL, token }, context) {
    const query = new URLSearchParams({
      src,
      width: String(modifiers.width ?? ''),
      quality: String(modifiers.quality ?? '')
    });

    if (token) query.set('token', token);

    return {
      url: `${baseURL}?${query}`,
      isOptimized: true
    };
  }
});

export const acmeProvider = configureProvider(
  setup,
  {
    baseURL: 'https://images.example.com/transform'
  },
  'acme'
);
```
```

--------------------------------

### Configure Vite plugin in vite.config.ts

Source: https://github.com/desource-labs/image/blob/main/packages/svelte/README.md

Add the dsImage Vite integration after installing ipx. The plugin serves /_ipx in Vite development and preview, and bakes the detected provider into client and server bundles so hydration uses the same provider.

```ts
// vite.config.ts
import { dsImage } from '@desource/image-svelte/vite';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [dsImage({ dirs: ['static'] }), sveltekit()]
});
```

--------------------------------

### Callable helper with useDsImage

Source: https://github.com/desource-labs/image/blob/main/packages/react/README.md

Use the `useDsImage` hook to get a callable helper that generates image URLs. The helper exposes `getImage`, `getSizes`, `getMeta`, `getAttrs`, `getPicture`, `getPreloadLink`, and configured preset shortcuts.

```tsx
import { useDsImage } from '@desource/image-react';

function Avatar({ src }: { src: string }) {
  const image = useDsImage();
  return <img src={image(src, { width: 96, height: 96, fit: 'cover' })} alt="" />;
}
```

--------------------------------

### Responsive image with sizes and densities

Source: https://github.com/desource-labs/image/blob/main/packages/angular/README.md

Use the `sizes` attribute with a breakpoint shorthand string and `densities` to generate responsive `srcset` and `sizes` attributes. The core engine deduplicates candidate widths and clamps them to provider-supported sizes.

```html
<ds-image src="/img/gallery.jpg" alt="Gallery" width="1200" sizes="100vw sm:50vw lg:600px" densities="1x 2x" />
```

--------------------------------

### Run the full release gate

Source: https://github.com/desource-labs/image/blob/main/README.md

Runs formatting, linting, Changesets status, peer checks, production audit, package builds, demo builds, type checks, package metadata validation, unit coverage, and e2e tests.

```sh
pnpm check:release
```

--------------------------------

### Import helpers from @desource/image/kit

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Import the small helper functions provided by the framework integration kit subpath. The subpath is limited to framework glue; provider URL logic stays in the main package and rendering lifecycle stays in the framework packages.

```TypeScript
import {
  isResolvedImageConfig,
  mergeClassNames,
  normalizeCrossorigin,
  stripUndefined,
  styleWithPlaceholder
} from '@desource/image/kit';
```

--------------------------------

### Configure Vercel adapter images in svelte.config.js

Source: https://github.com/desource-labs/image/blob/main/packages/svelte/README.md

Configure @sveltejs/adapter-vercel so its Build Output API contains image settings. Keep adapter image sizes and allowed remote domains aligned with the application configuration.

```js
// svelte.config.js
import adapter from '@sveltejs/adapter-vercel';

export default {
  kit: {
    adapter: adapter({
      images: {
        sizes: [640, 768, 1024, 1280, 1536],
        domains: ['images.example.com'],
        minimumCacheTTL: 2678400,
        formats: ['image/avif', 'image/webp'],
        dangerouslyAllowSVG: false
      }
    })
  }
};
```

--------------------------------

### Register convenience providers for common deployment paths

Source: https://github.com/desource-labs/image/blob/main/packages/angular/README.md

Imports and calls convenience providers for IPX, Vercel, and AWS Amplify image services. These providers are designed for common deployment paths.

```TypeScript
import { provideDsAwsAmplifyImage, provideDsIpxImage, provideDsVercelImage } from '@desource/image-angular';

provideDsIpxImage();
provideDsVercelImage();
provideDsAwsAmplifyImage();
```

--------------------------------

### Configure dsImage Vite plugin in vite.config.ts

Source: https://github.com/desource-labs/image/blob/main/packages/react/README.md

Adds the dsImage Vite plugin to serve /_ipx during development and preview, and bakes a deterministic provider into client and SSR bundles for consistent hydration.

```ts
// vite.config.ts
import { dsImage } from '@desource/image-react/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [dsImage({ dirs: ['public'] })]
});
```

--------------------------------

### getPreloadLink()

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Returns responsive <link rel="preload" as="image"> attributes.

```APIDOC
## getPreloadLink()

### Description
Returns responsive <link rel="preload" as="image"> attributes.

### Returns
- **object** - Responsive <link rel="preload" as="image"> attributes.
```

--------------------------------

### createDsImageBindings() with shared config

Source: https://github.com/desource-labs/image/blob/main/packages/svelte/README.md

Bind one configuration once for several native elements. The returned functions no longer need a config field in every options object.

```svelte
<script lang="ts">
  import { createDsImageBindings, createDsImageConfig } from '@desource/image-svelte';

  const config = createDsImageConfig({ provider: 'ipx' });
  const { dsImageAction, dsImageAttachment, dsPictureAction, dsPictureAttachment } = createDsImageBindings(config);
</script>
```

--------------------------------

### getImagePreloadLink()

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Stateless helper that returns responsive <link rel="preload" as="image"> attributes.

```APIDOC
## getImagePreloadLink()

### Description
Stateless helper that returns responsive <link rel="preload" as="image"> attributes.

### Returns
- **object** - Responsive <link rel="preload" as="image"> attributes.
```

--------------------------------

### Supported sizes forms (text)

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Lists the accepted `sizes` string formats: a single viewport width like `100vw`, responsive breakpoints with `sm:`/`md:` prefixes, and a combination of viewport and fixed pixel widths.

```text
100vw
sm:100vw md:50vw lg:400px
100vw md:760px
```

--------------------------------

### createImageContext(config)

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Creates an image context with resolved config and bound methods.

```APIDOC
## createImageContext(config)

### Description
Creates an image context with resolved config and bound methods.

### Parameters
- **config** (ImageConfig) - Required - The image configuration object.

### Returns
- **object** - The resolved config plus bound `getImage`, `getImageAttrs`, `getPictureAttrs`, `getPreloadLink`, and `getMeta` methods.
```

--------------------------------

### Callable image helper with useDsImage

Source: https://github.com/desource-labs/image/blob/main/packages/svelte/README.md

Use the callable helper to generate image URLs with options like width, format, and quality. It exposes getImage, getSizes, getMeta, getAttrs, getPicture, getPreloadLink, and configured preset shortcuts.

```svelte
<script lang="ts">
  import { useDsImage } from '@desource/image-svelte';

  const $img = useDsImage();
  const hero = $img('/img/hero.jpg', { width: 800, format: 'webp', quality: 75 });
</script>
```

--------------------------------

### Placeholder and preload attributes

Source: https://github.com/desource-labs/image/blob/main/packages/angular/README.md

Use `placeholder` to generate a small transformed image, optionally with a tuple for width, height, quality, and blur, or a custom URL/data URL. `placeholderClass` is present only while the placeholder is visible. The full image is preloaded off-screen and replaces the placeholder after decode succeeds. `preload` inserts a responsive `<link rel="preload" as="image">` into the document head; identical links are reference-counted and removed during teardown. `priority` sets eager loading and high fetch priority.

```html
<ds-image src="/img/hero.jpg" alt="Hero" width="1200" placeholder placeholderClass="blur" />
```

```html
<ds-image src="/img/hero.jpg" alt="Hero" width="1200" [placeholder]="[48, 32, 25, 8]" />
```

```html
<ds-image src="/img/hero.jpg" alt="Hero" width="1200" placeholder="data:image/png;base64,..." />
```

--------------------------------

### getAttrs()

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Returns native <img> attributes, placeholder URL, and placeholder class.

```APIDOC
## getAttrs()

### Description
Returns native <img> attributes, placeholder URL, and placeholder class.

### Returns
- **object** - Native <img> attributes, placeholder URL, and placeholder class.
```

--------------------------------

### Use NgOptimizedImage with provideDsImage

Source: https://github.com/desource-labs/image/blob/main/packages/angular/README.md

Shows how the same configuration powers NgOptimizedImage. The component imports NgOptimizedImage and uses ngSrc.

```ts
import { NgOptimizedImage } from '@angular/common';
import { Component } from '@angular/core';

@Component({
  standalone: true,
  imports: [NgOptimizedImage],
  template: `<img ngSrc="/img/hero.jpg" alt="Mountain lake" width="1200" height="800" />`
})
export class HeroComponent {}
```

--------------------------------

### createDsImageBindings(config)

Source: https://github.com/desource-labs/image/blob/main/packages/svelte/README.md

Creates a set of binding functions for native elements that share an explicit configuration. The returned functions no longer require a config field in every options object.

```APIDOC
## createDsImageBindings(config)

### Description
Creates a set of binding functions for native elements that share an explicit configuration. The returned functions no longer require a config field in every options object.

### Parameters
- **config** (object) - Required - The configuration object created by `createDsImageConfig()`.

### Returns
- **dsImageAction** (function) - A Svelte action for image elements.
- **dsImageAttachment** (function) - An attachment for image elements.
- **dsPictureAction** (function) - A Svelte action for picture elements.
- **dsPictureAttachment** (function) - An attachment for picture elements.

### Example
```svelte
<script lang="ts">
  import { createDsImageBindings, createDsImageConfig } from '@desource/image-svelte';

  const config = createDsImageConfig({ provider: 'ipx' });
  const { dsImageAction, dsImageAttachment, dsPictureAction, dsPictureAttachment } = createDsImageBindings(config);
</script>
```
```

--------------------------------

### Provider-authoring utilities

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Reusable provider primitives exported from the main entry for building custom providers.

```APIDOC
## Provider-authoring utilities

### Description
Reusable provider primitives exported from the main entry for building custom providers.

### Method
N/A (TypeScript exports)

### Endpoint
N/A

### Exports
- `defineProvider`
- `configureProvider`
- `resolveProviderRegistration`
- `createMappedQueryProvider`
- `mappedQueryURL`
- `mappedModifiers`
- `pathOperations`
- `appendProviderModifiers`
- `withStandardParams`
- `providerBaseURL`
- `sourceWithBase`
- `sourcePath`
- `joinURLParts`
- `cleanColor`
- `formatJpgValue`
- `defaultFitValue`
- `createMapper`
- `createOperationsGenerator`
- `appendQuery`
- `stableModifiers`
- `normalizeFormat`
- `mimeForFormat`
```

--------------------------------

### Create Next.js image loader with createNextImageLoader

Source: https://github.com/desource-labs/image/blob/main/packages/react/README.md

Create a custom loader for `next/image` using `createNextImageLoader` from `@desource/image-react/next`. Configure the provider (e.g., 'vercel') to let DeSource Image own the provider URL rules.

```ts
// ds-loader.ts
import { createNextImageLoader } from '@desource/image-react/next';

export const dsLoader = createNextImageLoader({
  provider: 'vercel'
});
```

--------------------------------

### Import all built-in providers

Source: https://github.com/desource-labs/image/blob/main/README.md

Use this import to access all built-in provider modules at once. The default registry is intentionally small, so import all built-in provider modules only when needed.

```TypeScript
import { BUILT_IN_PROVIDER_NAMES, createBuiltInProviders } from '@desource/image/providers';
```

--------------------------------

### Register imagekit provider and preset with DsImageProvider

Source: https://github.com/desource-labs/image/blob/main/packages/react/README.md

Configures the DsImageProvider with the imagekit provider and a 'card' preset, then uses DsImage with that preset. Provider modules and custom-provider utilities are documented in the core package.

```tsx
import { DsImageProvider } from '@desource/image-react';
import { imagekitProvider } from '@desource/image/providers/imagekit';

export function App() {
  return (
    <DsImageProvider
      config={{
        provider: 'imagekit',
        providers: {
          imagekit: imagekitProvider({ baseURL: 'https://ik.imagekit.io/demo' })
        },
        presets: {
          card: { width: 960, height: 640, sizes: '100vw md:480px', format: 'webp' }
        }
      }}
    >
      <DsImage preset="card" src="/products/chair.jpg" alt="Oak chair" />
    </DsImageProvider>
  );
}
```

--------------------------------

### Run quality checks before submitting a pull request

Source: https://github.com/desource-labs/image/blob/main/CONTRIBUTING.md

Run these commands to verify linting, formatting, type checking, builds, fixtures, demo, unit tests, end-to-end tests, and package validation. Add focused tests for behavior changes; use shared contracts in common/test for shared API behavior.

```sh
pnpm lint
pnpm format:check
pnpm typecheck
pnpm build
pnpm build:fixtures
pnpm build:demo
pnpm test:unit
pnpm test:e2e
pnpm validate:packages
```

--------------------------------

### Use DeSource Image loader with next/image

Source: https://github.com/desource-labs/image/blob/main/packages/react/README.md

Pass the `dsLoader` to `next/image`'s `loader` prop to keep `next/image` rendering behavior while DeSource Image owns the provider URL rules.

```tsx
import NextImage from 'next/image';
import { dsLoader } from './ds-loader';

export function Hero() {
  return <NextImage loader={dsLoader} src="/img/hero.jpg" alt="Hero" width={1200} height={800} />;
}
```

--------------------------------

### getImageSizes()

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Stateless helper that returns normalized srcset, sizes, candidate widths, and descriptor data.

```APIDOC
## getImageSizes()

### Description
Stateless helper that returns normalized srcset, sizes, candidate widths, and descriptor data.

### Returns
- **object** - Normalized srcset, sizes, candidate widths, and descriptor data.
```

--------------------------------

### DsImage component usage with preload and placeholder

Source: https://github.com/desource-labs/image/blob/main/packages/svelte/README.md

Use DsImage to render an optimized <img> with responsive sizes, WebP format, quality, placeholder, and preload. `alt` is required; native image attributes and Svelte event properties pass through to the generated <img>.

```svelte
<script lang="ts">
  import { DsImage } from '@desource/image-svelte';

  let loaded = $state(false);
</script>

<DsImage
  src="/img/hero.jpg"
  alt="Aurora above a mountain lake"
  width={1600}
  height={900}
  sizes="100vw md:50vw lg:800px"
  format="webp"
  quality={82}
  placeholder
  preload={{ fetchPriority: 'high' }}
  class="hero"
  onload={() => (loaded = true)}
/>
```

--------------------------------

### Svelte actions for native elements (dsImageAction, dsPictureAction)

Source: https://github.com/desource-labs/image/blob/main/packages/svelte/README.md

Use these actions to add reactive image behavior to native <img> and <picture> elements. The picture action requires one fallback <img> and manages generated <source> elements around it.

```svelte
<script lang="ts">
  import { dsImageAction, dsPictureAction } from '@desource/image-svelte';

  let width = $state(720);
  const imageOptions = $derived({
    src: '/img/card.jpg',
    alt: 'A coastal village',
    width,
    height: 480,
    densities: '1x 2x',
    placeholder: true
  });
</script>

<img alt="A coastal village" use:dsImageAction={imageOptions} />

<picture
  use:dsPictureAction={{
    src: '/img/card.jpg',
    alt: 'A coastal village at sunset',
    width,
    height: 480,
    formats: ['avif', 'webp']
  }}
>
  <img alt="A coastal village at sunset" />
</picture>
```

--------------------------------

### ImageConfig with cloudinaryProvider

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Configuration object for the image optimizer. Uses the Cloudinary provider, sets default quality and format, defines responsive screens, densities, provider sizes, aliases, domains, patterns, presets, and provider options. `resolveImageConfig(config)` normalizes this once; `createImageContext(config)` returns the resolved config plus bound methods.

```ts
import type { ImageConfig } from '@desource/image';
import { cloudinaryProvider } from '@desource/image/providers/cloudinary';

export const config: ImageConfig = {
  provider: 'cloudinary',
  baseURL: '/',
  quality: 76,
  format: 'webp',
  screens: {
    sm: 640,
    md: 768,
    lg: 1024,
    xl: 1280
  },
  densities: [1, 2],
  providerSizes: [320, 480, 640, 768, 1024, 1280, 1536],
  aliases: {
    media: 'https://assets.example.com'
  },
  domains: ['assets.example.com'],
  localPatterns: [{ pathname: '/img/**' }],
  remotePatterns: [{ protocol: 'https', hostname: '*.example.com', pathname: '/media/**' }],
  presets: {
    card: {
      width: 960,
      height: 640,
      sizes: '100vw md:480px',
      format: 'webp'
    }
  },
  providers: {
    cloudinary: cloudinaryProvider({ cloudName: 'demo' })
  },
  providerOptions: {
    cloudinary: {
      modifiers: { quality: 'auto' }
    }
  },
  onInvalidSource: 'warn'
};
```

--------------------------------

### Add a changeset for published packages

Source: https://github.com/desource-labs/image/blob/main/CONTRIBUTING.md

Run this command to create a changeset. Use Conventional Commits and select every public package with the same summary because all four packages are released as a fixed group.

```sh
pnpm changeset
```

--------------------------------

### App Router IPX route handler

Source: https://github.com/desource-labs/image/blob/main/packages/react/README.md

Create an App Router route handler for local IPX URLs using `createNextImageRouteHandler`. Remote optimization is denied by default; add trusted `domains` or set `allowAllDomains: true` only for an intentionally public optimizer.

```ts
// app/_ipx/[...path]/route.ts
import { createNextImageRouteHandler } from '@desource/image-react/next';

export const GET = createNextImageRouteHandler({
  dirs: ['public'],
  domains: ['images.example.com'],
  maxAge: 60 * 60 * 24 * 30
});
```

--------------------------------

### DsImage with placeholder variants

Source: https://github.com/desource-labs/image/blob/main/packages/svelte/README.md

Responsive images with placeholders. A boolean placeholder generates a small transformed image; a tuple controls width, height, quality, and blur; a string is a data URI. The full image replaces the placeholder only after decode succeeds. placeholderClass is present only while the placeholder is visible.

```svelte
<DsImage src="/img/hero.jpg" alt="Hero" width={1200} placeholder placeholderClass="blur" />
<DsImage src="/img/hero.jpg" alt="Hero" width={1200} placeholder={[48, 32, 25, 8]} />
<DsImage src="/img/hero.jpg" alt="Hero" width={1200} placeholder="data:image/png;base64,..." />
```

--------------------------------

### getImage()

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Returns the provider result with URL and optimization metadata.

```APIDOC
## getImage()

### Description
Returns the provider result with URL and optimization metadata.

### Returns
- **object** - Provider result containing URL and optimization metadata.
```

--------------------------------

### Register defaults in app.config.ts

Source: https://github.com/desource-labs/image/blob/main/packages/angular/README.md

Optional configuration. Without an explicit provider, the shared engine detects Vercel, Netlify, or AWS Amplify and falls back to IPX. provideDsImage() also registers Angular's IMAGE_LOADER.

```ts
import { ApplicationConfig } from '@angular/core';
import { provideDsImage } from '@desource/image-angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideDsImage({
      quality: 80,
      screens: { sm: 640, md: 768, lg: 1024 },
      domains: ['images.example.com']
    })
  ]
};
```

--------------------------------

### Create callable helper service with DsImageService

Source: https://github.com/desource-labs/image/blob/main/packages/angular/README.md

Injects DsImageService and creates a callable helper for generating image URLs and attributes. The helper exposes additional methods like getImage, getSizes, getMeta, getPicture, getPreloadLink, and preset shortcuts.

```TypeScript
import { inject } from '@angular/core';
import { DsImageService } from '@desource/image-angular';

const $img = inject(DsImageService).create();

const url = $img('/img/hero.jpg', {
  width: 800,
  format: 'webp',
  quality: 75
});

const attrs = $img.getAttrs({
  src: '/img/hero.jpg',
  alt: 'Hero',
  width: 800
});
```

--------------------------------

### Angular standalone component using DsPictureComponent

Source: https://github.com/desource-labs/image/blob/main/packages/angular/README.md

Use this standalone Angular component to render a responsive <picture> with ordered <source> elements and a fallback <img>. Supports format aliases: format="avif,webp", [format]="['avif', 'webp']", and legacyFormat.

```TypeScript
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { DsPictureComponent } from '@desource/image-angular';

@Component({
  standalone: true,
  imports: [DsPictureComponent],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <ds-picture
      src="/img/hero.jpg"
      alt="Responsive mountain landscape"
      width="1600"
      height="900"
      sizes="100vw md:50vw lg:800px"
      [formats]="['avif', 'webp']"
      fallbackFormat="jpg"
      imgClass="hero"
    />
  `
})
export class HeroPictureComponent {}
```

--------------------------------

### Use DsImage component with preset

Source: https://github.com/desource-labs/image/blob/main/packages/svelte/README.md

Render an image using a configured preset. The preset 'avatar' is defined in the shared configuration and applied to the source image.

```svelte
<DsImage preset="avatar" src="/users/ada.jpg" alt="Ada" />
```

--------------------------------

### getSizes()

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Returns normalized srcset, sizes, candidate widths, and descriptor data.

```APIDOC
## getSizes()

### Description
Returns normalized srcset, sizes, candidate widths, and descriptor data.

### Returns
- **object** - Normalized srcset, sizes, candidate widths, and descriptor data.
```

--------------------------------

### generatePictureSources()

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Generates picture source data for responsive images.

```APIDOC
## generatePictureSources()

### Description
Generates picture source data for responsive images.

### Returns
- **array** - Array of picture source objects.
```

--------------------------------

### DsImage Component

Source: https://github.com/desource-labs/image/blob/main/packages/svelte/README.md

A Svelte component for responsive images with support for placeholders, preloads, and priority loading.

```APIDOC
## DsImage Component

### Description
A Svelte component for responsive images with support for placeholders, preloads, and priority loading.

### Props
- **src** (string) - Required - The image source URL.
- **alt** (string) - Required - The alt text.
- **width** (number) - Required - The image width.
- **placeholder** (boolean | array | string) - Optional - A boolean generates a small transformed image; a tuple controls width, height, quality, and blur; a string is a data URI.
- **placeholderClass** (string) - Optional - CSS class applied only while the placeholder is visible.
- **sizes** (string | record) - Optional - Breakpoint strings such as `100vw sm:50vw lg:600px` or a record.
- **densities** (string | number | array) - Optional - Candidate densities.
- **preload** (boolean) - Optional - Inserts a responsive `<link rel="preload" as="image">` into the head and reference-counts duplicate links.
- **priority** (boolean) - Optional - Sets eager loading and high fetch priority.

### Examples
```svelte
<DsImage src="/img/hero.jpg" alt="Hero" width={1200} placeholder placeholderClass="blur" />
<DsImage src="/img/hero.jpg" alt="Hero" width={1200} placeholder={[48, 32, 25, 8]} />
<DsImage src="/img/hero.jpg" alt="Hero" width={1200} placeholder="data:image/png;base64,..." />
```
```

--------------------------------

### Add IPX middleware in Angular SSR

Source: https://github.com/desource-labs/image/blob/main/packages/angular/README.md

Creates and mounts the image middleware before static-file and Angular SSR handlers. The middleware loads ipx lazily and only handles requests under /_ipx. Remote optimization is denied by default; add trusted domains or set allowAllDomains: true for a public optimizer.

```TypeScript
import { createDsImageMiddleware } from '@desource/image-angular/server';

app.use(
  createDsImageMiddleware({
    dirs: [browserDistFolder],
    domains: ['images.example.com'],
    maxAge: 60 * 60 * 24 * 30
  })
);
```

--------------------------------

### Hooks for native markup

Source: https://github.com/desource-labs/image/blob/main/packages/react/README.md

Use useDsImageProps and useDsPictureProps when a design system or template must own the final DOM. The hooks handle placeholder preload/decode state, load/error forwarding, and head preload links with reference counting.

```tsx
import { useDsImageProps, useDsPictureProps } from '@desource/image-react';

function NativeImage() {
  const img = useDsImageProps({
    src: '/img/card.jpg',
    alt: 'A coastal village',
    width: 720,
    height: 480,
    placeholder: true,
    className: 'card-image'
  });

  return <img {...img} />;
}

function NativePicture() {
  const picture = useDsPictureProps({
    src: '/img/card.jpg',
    alt: 'A coastal village at sunset',
    width: 720,
    height: 480,
    formats: ['avif', 'webp'],
    fallbackFormat: 'jpg',
    imgAttrs: { className: 'card-image' }
  });

  return (
    <picture {...picture.pictureProps}>
      {picture.sources.map((source) => (
        <source key={`${source.type}:${source.srcSet}`} {...source} />
      ))}
      <img {...picture.imgProps} />
    </picture>
  );
}
```

--------------------------------

### Responsive image sizes as object

Source: https://github.com/desource-labs/image/blob/main/packages/angular/README.md

Define `sizes` as an object with breakpoint keys and values. The engine uses this to generate deterministic `srcset` and `sizes` attributes.

```ts
sizes = { sm: '100vw', md: '50vw', lg: 600 };
```

--------------------------------

### DsPicture component usage with multiple formats

Source: https://github.com/desource-labs/image/blob/main/packages/svelte/README.md

Use DsPicture to render native <picture>, <source>, and <img> elements with multiple formats (AVIF, WebP) and a fallback format. Comma-separated `format="avif,webp"`, array `format`, and the `legacyFormat` alias are supported.

```svelte
<script lang="ts">
  import { DsPicture } from '@desource/image-svelte';
</script>

<DsPicture
  src="/img/hero.jpg"
  alt="Responsive mountain landscape"
  width={1600}
  height={900}
  sizes="100vw md:50vw lg:800px"
  formats={['avif', 'webp']}
  fallbackFormat="jpg"
  class="hero-frame"
  imgAttrs={{ class: 'hero' }}
/>
```

--------------------------------

### Use DeSource Image components directly in Next.js

Source: https://github.com/desource-labs/image/blob/main/packages/react/README.md

Use `DsImage` directly in a Next.js App Router client component. The main package entry is a client entry because placeholders and head preloads use browser lifecycle APIs.

```tsx
'use client';

import { DsImage } from '@desource/image-react';

export function ProductImage() {
  return <DsImage src="/products/chair.jpg" alt="Oak chair" width={1200} height={900} format="webp" />;
}
```

--------------------------------

### Repository structure overview

Source: https://github.com/desource-labs/image/blob/main/CONTRIBUTING.md

Shows the top-level directory layout of the monorepo, including core, framework packages, shared test contracts, demo, and scripts. Framework-neutral behavior belongs in core; reusable glue goes in @desource/image/kit.

```text
packages/core       Framework-agnostic runtime, kit utilities, and providers
packages/angular    Angular components, directives, SSR adapter, tests, and fixture
packages/react      React components, hooks, Next/Vite adapters, tests, and fixture
packages/svelte     Svelte components, action, attachment, Vite adapter, tests, and fixture
common/test         Shared behavioral contracts and browser-test helpers
demo                SSR SvelteKit documentation and interactive examples
scripts             Coverage and release automation
```

--------------------------------

### Register built-in or custom providers with presets

Source: https://github.com/desource-labs/image/blob/main/packages/angular/README.md

Registers a custom provider (cloudinary) and defines presets using provideDsImage. The preset 'avatar' is used in the ds-image component.

```TypeScript
import { cloudinaryProvider } from '@desource/image/providers/cloudinary';
import { provideDsImage } from '@desource/image-angular';

provideDsImage({
  provider: 'cloudinary',
  providers: {
    cloudinary: cloudinaryProvider({ cloudName: 'demo' })
  },
  presets: {
    avatar: { width: 96, height: 96, fit: 'cover', quality: 80 }
  }
});
```

```HTML
<ds-image preset="avatar" src="/users/ada.jpg" alt="Ada" />
```

--------------------------------

### Object syntax for sizes (TypeScript)

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Shows the object form of `sizes`, mapping breakpoint keys to viewport widths or pixel values. The `lg` key uses a numeric pixel value.

```ts
{
  sm: '100vw',
  md: '50vw',
  lg: 600
}
```

--------------------------------

### getDsImageProps() and getDsPictureProps() SSR helpers

Source: https://github.com/desource-labs/image/blob/main/packages/svelte/README.md

Generate typed native properties without mounting a component. Useful in snippets, SSR output, and integrations. Pass true as the second argument when the full image has already loaded and a configured placeholder should be skipped.

```ts
import { getDsImageProps, getDsPictureProps } from '@desource/image-svelte';

const image = getDsImageProps({
  src: '/img/hero.jpg',
  alt: 'Hero',
  width: 800,
  format: 'webp'
});

const picture = getDsPictureProps({
  src: '/img/hero.jpg',
  alt: 'Hero',
  width: 800,
  formats: ['avif', 'webp']
});
```

--------------------------------

### getPicture()

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Returns native <picture> data: ordered sources plus fallback image attrs.

```APIDOC
## getPicture()

### Description
Returns native <picture> data: ordered sources plus fallback image attrs.

### Returns
- **object** - Native <picture> data with ordered sources and fallback image attributes.
```

--------------------------------

### image(src, modifiers)

Source: https://github.com/desource-labs/image/blob/main/packages/core/README.md

Optimizes an image source and returns an optimized URL string.

```APIDOC
## image(src, modifiers)

### Description
Optimizes an image source and returns an optimized URL string.

### Parameters
- **src** (string) - Required - The source image URL or path.
- **modifiers** (object) - Optional - Image optimization modifiers (e.g., width, height, format, quality).

### Returns
- **string** - The optimized URL string.
```
Tokens:
Raw