Netlify Docs
Ask Netlify

Contact

Netlify Create /Asset sources /

Asset sources

Every Netlify Create 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 the Netlify Create application.
  • Custom sources: Websites that provide specific functionality to work with Netlify Create configuration.

See below for more information on each source type.

Asset sources can be managed in your project settings or with the new visual editor settings.

Can’t find project settings?

We’re rolling out new visual editor settings. If you can’t find your project settings, go to

Site configuration Visual editor
.

Or select the new settings icon next to your project name and choose Visual editor settings.

# 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 Netlify Create.

When received, Netlify Create 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 content 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 Netlify Create 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
      })
    }
  ]
});

# Example project

The following example projects demonstrate this feature in action:

See a list of all examples using the create-stackbit-app utility.

npx create-stackbit-app@latest --help