Create a custom image adapter

Deliver enhanced and optimized images for every user with your custom adapter.

An Image Adapter is a custom function that you can use to deliver enhanced and optimized images for every user with your custom adapter. It is a function that takes an image URL as input and returns a new image URL as output. The new image URL can be the same as the original image URL, or it can be a different image URL that is optimized for the user's device, browser, or network.

Getting Started

To get started, you need to create a custom adapter class. The class must extend the ImageAdapter domain which implements a supportSrc method, and a makeImageSrc method.

The supportSrc method is used to check if the image URL is valid for the current adapter. If the image URL is valid, the makeImageSrc method is called to generate the new image URL.

Creating an Image Adapter

Let's create two Image adapters that extends the base ImageAdapter class and implements two key methods: supportSrc for URL validation and makeImageSrc for URL transformation. For this example, we will create adapters for two popular image services: Unsplash and Lorem Picsum.

First, let's look at an adapter for Unsplash images:

my-extension/adapters/unsplash.ts

import { ImageAdapter } from "theme/components/atoms/Image/ImageAdapter";

class UnsplashAdapter extends ImageAdapter {
  supportSrc(src: string) {
    return src.includes("unsplash.com");
  }

  makeImageSrc(src: string) {
    // ... do something with the image URL
    return src;
  }
}

export default new UnsplashAdapter();

And here's a similar adapter for Lorem Picsum:

my-extension/adapters/lorem-picsum.ts

import { ImageAdapter } from "theme/components/atoms/Image/ImageAdapter";

class LoremPicsumAdapter extends ImageAdapter {
  supportSrc(src: string) {
    return src.includes("picsum.photos");
  }

  makeImageSrc(src: string) {
    // ... do something with the image URL
    return src;
  }
}

export default new LoremPicsumAdapter();

Registering an Image Adapter

To register an Image Adapter, you need to add it to the imageAdapters component. You can do this by adding it to a top level route or a layout for example.

my-extension/routes/_main.tsx

// Other imports ...

import imageAdapters from "theme/components/atoms/Image/adapters";
import UnsplashAdapter from "./adapters/unsplash";
import LoremPicsumAdapter from "./adapters/lorem-picsum";

// Original route code ...

export default function MainLayout() {
  const { headerNavigationMenu, footerNavigationMenu } =
    useLoaderData<typeof loader>();

  imageAdapters.register(UnsplashAdapter);
  imageAdapters.register(LoremPicsumAdapter);

  return (
    <Layout
      headerNavigationMenu={headerNavigationMenu}
      footerNavigationMenu={footerNavigationMenu}
    >
      <Outlet />
    </Layout>
  );
}

// ... original route code ...

Using an Image Adapter

All the built-in image components use the ImageAdapters by default to deliver enhanced and optimized images.

Changing the generated sources for srcSet

The ImageAdapter has two optional methods:

• getSupportedExtensions this allows you to change how the srcSet is generated.
• getDefaultExtension this allows you to change the default format used for the srcSet.

For example, if we want to change the supported formats for the UnsplashAdapter:

my-extension/adapters/unsplash.ts

import { ImageAdapter } from "theme/components/atoms/Image/ImageAdapter";

class UnsplashAdapter extends ImageAdapter {
  supportSrc(src: string) {
    return src.includes("unsplash.com");
  }

  makeImageSrc(src: string) {
    return src;
  }

  getSupportedExtensions(transparent: boolean) {
    if (transparent) {
      return ["webp", "png"];
    }

    return ["webp", "jpeg"];
  }

  getDefaultExtension() {
    return "jpeg";
  }
}

You can also opt-out of multiple sources for the srcSet by either returning a single format or a null if you don't want to specify a format.

my-extension/adapters/unsplash.ts

  getSupportedExtensions(transparent: boolean) {
    if (transparent) {
      return "webp" // return a single format
    }

    return null // generate one source without a format specification
  }

note

Not specifying the getSupportedExtensions and getDefaultExtension methods will fallback to the default implementation.

For more information on image adapters provided by Front-Commerce, please refer to the Image Adapters documentation.