Assets

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

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

referenceType

• Allowed values: static or relative
• Required: true

The assets.referenceType specifies how content files reference asset files. Allowed values: static, relative.

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.

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

staticDir

The directory relative to the project root containing static files. Usually, the static site generator will copy files from this directory to the publishDir when it builds your site.

For example, if your project uses Hugo or Gatsby, the static directory would be static, and if your project uses Next.js, the static directory would be public.

• Allowed values: Directory path relative to the project root
• Required: required when referenceType is static

publicPath

The public URL from which the static files, stored in the assets.staticDir, are publicly accessible.

• Allowed values: URL path relative to your site domain
• Required: required when referenceType is static

assetsDir

The common ancestor folder containing all the assets within your project. This folder can include files of different types. However, only files with specific extensions will be treated as assets (png, jpg, jpeg, gif, svg, ico, etc.).

• Allowed values: Directory path relative to the project root
• Required: required when referenceType is relative