Media

Technical reference for configuring media asset providers.

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

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

Paid Feature

Use of media providers is limited to paid plans.

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:

If your preferred media provider is not listed, please contact us for details on supporting your service.

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).

assets

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

Required
When using files content source (Git CMS) and storing assets in the repository
Options

referenceType (required): Specifies how content files reference asset files. Options: static, relative.

uploadDir (required): Path inside assetsDir in which to store uploaded assets, relative to either staticDir (for static assets) or assetsDir (for relative assets).

Additional properties for static assets:

  • staticDir: Directory path relative to the project root in which the site framework copies files to the directory that get deployed.

  • publicPath: URL from which the static files are publicly available.

Additional properties for relative assets:

  • assetsDir: Path to the directory containing all the assets to your project, relative to the project root.

Static Assets

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

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
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.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
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.