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#

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:

Cloudinary

Cloudinary enables you to transform images and videos to load faster with no visual degradation, automatically generate image and video variants, and deliver high quality responsive experiences to increase conversions.

View Cloudinary Docs

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.

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.