stackbit.yaml [Deprecated]

Introduction#

stackbit.yaml is a configuration file that is required for our visual editor and our default managed hosting to function correctly. It should always be located at the root of your repository.

This file defines:

1. Which framework is used to run the project (e.g. Next.js, Angular, etc.), plus optional properties for customizing the commands and directories used.
2. Which models should the visual editor allow to instantiate, either as pages or as standalone content pieces. For each of these models, where to store new content files and the URL mapping of content.
3. Connecting an external headless CMS (rather than storing content as files in Git).

Note: you are free to build and run your website anywhere. This file is not needed for running your website in production.

Example#

Here is an example of a stackbit.yaml file for a simple site using Contentful as its content source:

stackbitVersion: ~0.6.0
ssgName: nextjs
nodeVersion: '16'
cmsName: contentful

modelsSource:
  type: contentful

models:
  page:
    type: page
    urlPath: '/{slug}'

Properties#

stackbitVersion#

• Allowed values: A valid version number in semver syntax.
  The current version is 0.6.0. Versions prior to 0.4.0 are deprecated.
• Required: Yes

We recommend using the latest version with a tilde: ~0.6.0, which explicitly defines that your project is not conflicting with any feature introduced in 0.5.x.

ssgName#

• Allowed values: nextjs, angular, gatsby, custom
• Required: Yes

The web framework used in your project. For any framework not listed here, you can use the value custom.

In that case, you will also need to define devCommand and typically a few additional properties. Learn more.

Integration guides & examples are available for multiple frameworks. To inquire about support for any other framework, talk to us.

cmsName#

• Allowed values: git, contentful, sanity
• Required: No
• Default: git

The name of the CMS your project is configured to work with. If your project uses our built-in mechanism for storing content in your Git repository, you don't need to specify this property.

customContentReload#

• Allowed values: true/false
• Required: No
• Default: false

Starting with version 0.5.0, this attribute specifies whether your code takes care of refreshing pages on content changes by itself.

By default (when the value is false), Stackbit will automatically detect content changes made by any content editor and refresh the page, attempting to do so in a efficient manner that's specific to the web framework used. You can augment or override this behavior via client-side code.

When set to true, Stackbit will not try any automatic refresh. Rather, it is your responsibility as a developer to have your code detect content changes and efficiently refresh the page. This is referred to as a custom content reload implementation.

Existing projects still using stackbitVersion: ~0.4.0 mostly depend on the Sourcebit package to implement this functionality.

To learn more, see Automatic Content Reload.

nodeVersion#

• Allowed values: a major version of Node.js as a string. Currently we support versions 12, 14, 16.
• Required: No
• Default: "14"

The version of Node.js used to install dependencies and run your website's server. Stackbit always uses the latest patch release for the major version you specified.

import#

• Allowed values: object, as referenced below.
• Required: only required for repositories that you want to be able to duplicate from GitHub and which use an externcal CMS.

If your theme works with an API-based CMS, such as Contentful or Sanity, you might want to have an initial content which will be imported into the CMS when Stackbit creates a new site from your theme.

When user creates a new site from a theme powered by API-based CMS, Stackbit Site Builder can provision the CMS with the initial theme content. As part of the provisioning process, Stackbit Site Builder will create a CMS project, import the content schema, and the initial content located in a special "export" file previously exported from the CMS. The "export" file can be created using the tools provided by CMS, such as CLI.

Stackbit will also generate any access tokens required by the static site generator to fetch the content from CMS, and will setup webhooks needed to trigger the deployment platform when the user publishes the content inside CMS.

To support this automatic provisioning, you will need to provide the import object.

Contentful#

If your theme uses Contentful as the headless-CMS, you can export the content schema and the initial site contents into a JSON file. Then set the following import properties in stackbit.yaml:

• contentFile: Path to the export file (relative to the root of your project).
• spaceIdEnvVar, deliveryTokenEnvVar, previewTokenEnvVar: The names of the environment variables used by your site.
• uploadAssets, assetsDirectory: If you would like assets to be uploaded, specify the export directory. From there, your contentFile will specify the location of individual assets.

Default values shown below:

stackbitVersion: ~0.3.0
ssgName: gatsby
cmsName: contentful
import:
  type: contentful
  contentFile: contentful/export.json
  uploadAssets: true
  assetsDirectory: contentful
  spaceIdEnvVar: CONTENTFUL_SPACE_ID
  deliveryTokenEnvVar: CONTENTFUL_DELIVERY_TOKEN
  previewTokenEnvVar: CONTENTFUL_PREVIEW_TOKEN

Example

Our Contentful starter has a contentful directory with an example of an export. The stackbit.yaml config's import property matches the code snippet shown above.

Sanity#

If your theme uses Sanity as the headless-CMS, you can export the content schema and the initial site contents into an NDJSON file. Specify the path to this file in the contentFile property. You should also provide the names of the environment variables for the project ID, the dataset, and the token expected by your static site generator to fetch the data from Sanity. Use projectIdEnvVar, datasetEnvVar and tokenEnvVar to specify the environment variable name for the project ID, the dataset, and the token, respectively.

You can also set the boolean flags deployStudio and deployGraphql to ensure that Stackbit deploys Sanity Studio and Sanity GraphQL API when creating the site. Note, gatsby-source-sanity plugin might require having Sanity GraphQL API endpoint in order to work properly.

For example, if your theme uses Gatsby you need to specify the names of the environment variables used to configure the gatsby-source-sanity plugin.

stackbit.yaml:

stackbitVersion: ~0.3.0
ssgName: gatsby
cmsName: sanity
import:
  type: sanity
  contentFile: sanity-export.tar.gz
  sanityStudioPath: studio
  deployStudio: true
  deployGraphql: true
  projectIdEnvVar: SANITY_PROJECT_ID
  datasetEnvVar: SANITY_DATASET
  tokenEnvVar: SANITY_TOKEN

Example for gatsby-config.js with gatsby-source-sanity configured to read projectId, dataset and token options from SANITY_PROJECT_ID, SANITY_DATASET and SANITY_TOKEN environment variables respectively:

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-sanity`,
      options: {
        projectId: process.env.SANITY_PROJECT_ID,
        dataset: process.env.SANITY_DATASET,
        token: process.env.SANITY_TOKEN,
      },
    },
  ],
}

buildCommand#

devCommand#

• Allowed values: a string specifying the command that runs your website's server in development mode.
• Required: only if ssgName is set to custom, optional otherwise.

Set a custom command to run your development server. By default, unless you've defined ssgName: custom in your configuration file, Stackbit will infer this command based on the ssgName value.

When customizing the dev command, pay attention to:

• The current working directory is your code's root directory. This means that various scripts installed by NPM packages are to be found in ./node_modules/.bin/.
• Your server should accept requests from hosts other than localhost (or 127.0.0.1).
• The port to listen on should always be configurable. In the command you specify include the {PORT} placeholder, which will be substituted when we run the command.

Examples

For Next.js: (this is the default with ssgName: nextjs)

devCommand: ./node_modules/.bin/next dev --port {PORT}`

For Angular:

devCommand: ./node_modules/.bin/ng serve  --port {PORT} --disable-host-check`

For SvelteKit:

devCommand: ./node_modules/.bin/vite --port {PORT}`

publishDir#

pagesDir#

• Allowed values: a string specifying a directory path relative to the project root.
• Required: When using the built-in Git CMS.

Defines the root directory of page content. This works in tandem with model mapping.

excludePages#

• Allowed values: a list of file paths, or glob patterns.
• Required: false.

If your pagesDir contains files that have markdown extensions (.md, .mdx, .markdown) but should not be treated as site pages, use the excludePages property to specify which files should not be treated as site pages. The value should be a glob string or a list of glob strings matching files that should be excluded.

Example

stackbitVersion: ~0.6.0
ssgName: nextjs
pagesDir: content
excludePages:
  - internal/**/*
  - README.md

dataDir#

• Allowed values: a string specifying a directory path relative to the project root.
• Required: When using the built-in Git CMS.

Defines the root directory of non-page content, e.g. global configuration, team members or authors that are linked from multiple pages, and more. This works in tandem with model mapping.

pageLayoutKey#

• Allowed values: the property name in stored pages which defines their model type
• Required: No
• Default: layout

This property is explicitly set tolayout in all of our themes for backward compatibility. At this time, leave this value as is.

In future versions, both the default value (when this property is omitted) and the value explicitly set by our starters & examples may change to type for more consistency with other content items. However, existing projects where this property is explicitly set will not be affected.

objectTypeKey#

• Allowed values: the field name of data models to identify the type of the object
• Required: false
• Default: type

The objectTypeKey defines the field name of data models that will be used to identify the type of the objects referenced by the model or reference fields.

styleObjectModelName#

• Allowed values: Any valid model name
• Default: ThemeStyle

Defines the name of the model used for storing global style values.

assets#

• Allowed values: an object, with the properties as described below.
• Required: When using the built-in Git CMS.

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 web framework you use will copy files from this directory to the its output directory when building 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

models#

• Allowed values: an array of content model schema definitions, which can also be defined in individual files within the .stackbit/models directory when using a local content source.
• Required: Yes

Provides the schema definition for the models in your project. See the model properties guide for available properties.

modelsSource#

Allowed values: An object containing a list of directory paths, either in your project or its dependencies - see example.

Required: No

Default:

modelsSource:
  type: files
  modelDirs:
    - .stackbit/models

If you add additional entries to modelDirs, note that order is important: directories should be ordered in the property from lower to higher precedence. Models defined in higher precedence directories override models of the same name in the other locations, if such duplicates exist.

Usually, you do not need to change this property from its default value. However, this is useful for loading models defined in other 3rd party packages you've installed.

Be careful not to add any paths which are neither within your project nor its dependencies, as the project will not work properly in our visual editor and default hosting service.

For each of the directories in the list, Stackbit will search for model files (with either .yaml or .yml extension) in all sub-directories.

presetSource#

Allowed values: An object with type and presetDirs defined.

Required: No

Options:

• type: Currently only files is supported.
• presetDirs: An array of directory paths, relative to the root of the project, from which to load presets. This can include directories within node_modules.

Example:

presetSource:
  type: files
  presetDirs:
    - node_modules/some-package/.stackbit/presets
    - my-presets

Handling Preset Conflicts#

All presets in all directories are loaded, regardless of any conflicts in model name or preset label.

Common Preset Directories#

Regardless of the directories provided in presetDirs, the following directories will be included:

• .stackbit/presets
• node_modules/@stackbit/components/presets

Model Structure Inconsistencies#

Ensure that presets being brought in from packages match the structure of the model that you're using in your project. Presets mismatching the schema of the model they represent are not currently supported.

User-Created Components#

Presets created by content editors will be placed in the .stackbit/presets directory. This behavior is not affected by these settings.

presetReferenceBehavior#

Specifies how to handle references when creating new content from a preset.

presetReferenceBehavior: copyReference | duplicateContents

Options:

• copyReference (default): Reference(s) are copied directly. The new content will use the same references as the original content. (See duplicatableModels for providing exceptions.)
• duplicateContents: Reference(s) are duplicated. The new content will refer to the newly duplicated content and will not affect the original referenced content. (See nonDuplicatableModels for providing exceptions.)

Example:

Suppose a PostFeed component preset that includes a reference to a list of featured posts. If copyReference is used, when new content is created, it will refer to the same posts stored in the preset.

If instead duplicateContents is used, each post referenced in the preset will be duplicated, and the new posts will be used for the new content.

duplicatableModels#

when presetReferenceBehavior is set to copyReference, this field specifies a list of exceptions. If a model appears in this list, it will be duplicated. Every other model respects the copyReference setting.

presetReferenceBehavior: copyReference
duplicatableModels:
  - Post

nonDuplicatableModels#

when presetReferenceBehavior is set to duplicateContents, this field specifies a list of exceptions. If a model appears in this list, it will NOT be duplicated. Every other model respects the duplicateContents setting.

presetReferenceBehavior: duplicateContents
nonDuplicatableModels:
  - Post

Experimental#

Properties under the experimental entry may be subject to change in the future. These are mostly meant to provide tighter integration between various web frameworks and Stackbit.

These properties are to be used in conjunction with ssgName: custom (reference), and are usually not needed otherwise.

Here's an example of experimental properties used for integrating with a SvelteKit-baseds site (SvelteKit guide, Hydrogen guide):

# In stackbit.yaml...

experimental:
  ssg:
    name: sveltekit
    logPatterns:
      up: ' ready in '
    passthrough:
      - '/vite-hmr/**'

experimental.ssg.logPatterns.up#

When we run your website's server, it typically takes some time before the server process is ready to accept requests - from as few seconds to a few dozen seconds.

To prevent the visual editor from making requests to the server too soon and causing errors or timeouts set this property to the log message that is printed when the server is ready, or any portion of it which is always printed to console exactly in the same way.

experimental.ssg.passthrough#

Many frameworks use a Websocket connection in development mode between the client and server, to trigger a client-side refresh on code changes (a.k.a. HMR or Hot Module Replacement. This is usually handled at the Webpack/Vite level).

Set this property to the relative path of the websocket endpoint on the server, to prevent our container from any interference with it. You may also need to define this path in your Webpack's/Vite's configuration.