Assets

If your project is configured to work with API-based CMS such as Contentful, your assets will be stored in that CMS. Therefore, you don't need to define this property.

The assets object defines where site assets (such as images) are stored in your project, and how other content references these assets.

The first property to note is referenceType, which could be set to either static or relative. Here's what that means, and how to setup the other properties accordingly.

Using Static Assets

Here's an example configuration for this object using static assets. This configuration is currently used in our themes, as it's appropriate for use with Next.js.

stackbitVersion: ~0.4.0
# ...
assets:
  referenceType: static
  staticDir: public
  uploadDir: images
  publicPath: /

When referenceType is set to static:

• All assets must be placed under the directory set in staticDir, either directly or in sub-directories. 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.

Additionally, our UI allows content creators to upload new images. These would be saved in the location {staticDir}/{uploadDir}, or in the above case: public/images/.

Using Relative Assets

With Gatsby, it is a valid option to store image files co-located with content rather than under a single dedicated directory. This requires setting referenceType to: relative.

Here's an example:

assets:
  # Assets are referenced using relative paths
  referenceType: relative
  # The common ancestor folder containing all images is the 'src' folder
  assetsDir: src
  # Uploaded images will be stored in 'src/uploads'
  uploadDir: uploads

This is just one example configuration. Support for configuring Stackbit in a manner which conforms to your Gatsby code is available in premium plans.