Media

Stackbit can work with any media provider you choose to use, which tend to fall into one of three categories:

• Built-in services from API CMSs
• Third-party media providers
• Storing directly in the repository (for file-based content)

API CMS#

If your project is configured to work with API-based CMS (Contentful, Sanity, etc.), your assets will be stored in that CMS.

Stackbit knows how to work with media from headless CMS providers. All you need to do is configure the content source appropriately using the contentSource property. The best way to do this is to find the appropriate integration guide.

Media Providers#

Regardless of your content source, you have the option to use a third-party media provider. These services are configured through the Stackbit application. See below for supported providers:

Custom Asset Sources#

In cases where there isn't a direct integration with an asset provider and where you want to use a different asset source than what is provided by the content source, you can use the assetSources property to bring your own behavior.

assetSources#

Defines a custom source to be used selectively by image fields.

This is currently referring specifically to custom iframe sources. Other third-party sources are available as direct integrations. See the integration guides for usage information.

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' }],
    },
  ],
})

Storing Media in Repository#

If you're using files as your content source (Git CMS), you can also choose to store media files within your repository. Use the assets property (documented below).

The assets object defines where local site assets are stored in your project, and how other content references these assets.

Static Assets#

Here's an example configuration for this object using static assets. This is a common configuration when using Next.js.

export default {
  cmsName: 'git',
  assets: {
    referenceType: 'static',
    staticDir: 'public',
    uploadDir: 'images',
    publicPath: '/',
  },
  // other properties ...
}

• All assets must be placed under the directory set in staticDir, either directly or in subdirectories. They cannot be colocated with page content or source code. The value is always relative to the root of the project.
• When the build is run, assets are served from the URL path set by publicPath. The full URLs are constructed as {publicPath}/{file path under staticDir}.
• With the example configuration above, an image file named public/creatives/car.png in your repository will be served from the URL /creatives/car.png.
• Images uploaded by editors would be saved in {staticDir}/{uploadDir}, or in the above case: {root}/public/images.

Relative Assets#

Gatsby is a framework in which asset files can be colocated with content, rather than under a single dedicated directory, allowing content to make use of relative assets.

export default {
  cmsName: 'git',
  assets: {
    referenceType: 'relative',
    assetsDir: 'src',
    uploadDir: 'images',
  },
  // other properties ...
}

• assetsDir can include files of different types. However, only files with specific extensions will be treated as assets (png, jpg, jpeg, gif, svg, ico, etc.).
• Images uploaded by editors would be saved in {assetsDir}/{uploadDir}, or in the above case: {root}/src/images.