Netlify Docs
Ask Netlify

Contact

Visual editing /Visual Editor /Asset sources /

Asset sources

Every visual editor content source must provide its own default asset storage mechanism. For most headless CMSs, this behavior is provided through the API. With Git CMS, the default behavior is to store files within the repository.

In some cases, you may wish to override the default behavior. This is common when wanting more features than a headless CMS provides, or when wanting to avoid storage large files in a repository.

There are two types of assets sources:

  • Direct integrations: Third-party asset managers that are tightly integrated into Visual Editor application.
  • Custom sources: Websites that provide specific functionality to work with Visual Editor configuration.

See below for more information on each source type.

Asset sources can be managed in your visual editor settings for Bynder or Aprimo. Learn more in our Cloudinary docs or Aprimo docs.

# Direct integrations

Adding a direct integration for assets will take over the behavior of how assets are retrieved and stored. See the following integration guides for usage and configuration options:

Tip

If your preferred media provider is not listed, contact us for details on supporting your service. Or, consider a looser integration by creating a custom source.

# Custom sources

Custom asset sources provide a way for you to flexibly bring your own asset behavior without the need of a direct integration.

# How custom sources work

Custom asset sources are web pages loaded into the selection modal via an <iframe> element.

Custom asset source selection modal.

Sources are defined using the assetSources property, as shown below.

The web page can include any features necessary for retrieving an image for your preferred source, including filtering, sorting, searching, or pagination.

The only required behavior is that an editor should be able to select an image (in any way, though usually by clicking on the image). This event should prompt the web page to call the postMessage method to send the desired data to Visual Editor.

When received, Visual Editor calls the transform property of the asset source configuration (if provided), and stores the resulting data in the appropriate content source.

# Custom source configuration

Custom asset sources should be configured using the assetSources property.

Once configured, individual image fields can attached to the custom source using the source property. This is usually done using modelExtensions or defining directly in the schema, depending on the content source.

// stackbit.config.ts
import { defineStackbitConfig } from "@stackbit/types";

export default defineStackbitConfig({
  stackbitVersion: "~0.6.0",
  contentSources: [
    // ...
  ],
  assetSources: [
    {
      name: "asset-source-name",
      type: "iframe",
      url: "https://www.asset-source-url.com",
      transform: ({ assetData }) => assetData.imageUrl,
      preview: ({ assetData }: { assetData: string }) => ({ image: assetData })
    }
  ],
  modelExtensions: [
    {
      name: "hero",
      type: "object",
      fields: [{ name: "image", type: "image", source: "asset-source-name" }]
    }
  ]
});

# Image previews

Image previews are used by Visual Editor when rendering an image field (or an object with an image field) in a form editor.

example image preview.

These previews are controlled by the preview property defined on the asset source.

Keep in mind that the assetData received by the function is in the same shape as it is stored in the content source. The example below assumes that the image data is stored as an object with a url property representing the image source.

// stackbit.config.ts
export default defineStackbitConfig({
  stackbitVersion: "~0.6.0",
  assetSources: [
    {
      name: "asset-source-name",
      type: "iframe",
      url: "https://www.asset-source-url.com",
      transform: ({ assetData }) => assetData.imageUrl,
      preview: ({ assetData }: { assetData: string }) => ({
        image: assetData.url
      })
    }
  ]
});