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.

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:

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.

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.

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.

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.

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