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 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
orrelative
- 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
isstatic
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
isstatic
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
isrelative