This page specifies the format of stackbit.yaml version 0.5.0 or later,
as specified in the stackbitVersion property.

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. On paid plans, 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.5.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.5.0. Versions prior to 0.4.0 are deprecated.
  • Required: Yes

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

ssgName

  • Allowed valuesnextjs, 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 valuesgitcontentful, sanity
  • Required: No
  • Defaultgit

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.

Note: external CMS's are supported only in our paid plans. To inquire about support for any CMS not listed here, talk to us.

customContentReload

Available starting from stackbitVersion 0.5.0
  • 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

Only relevant when using Contentful or Sanity as CMS.

  • Allowed values: import object (reference).
  • Required: only required for repositories that you want to be able to duplicate from GitHub and which use an externcal CMS.

Useful for examples and "template" repositories from which multiple projects are created. This property enables you to define an initial content model & content that will be imported into your CMS when duplicating from GitHub.

buildCommand

This property is used to configure Managed Hosting when creating a new project by duplicating a GitHub repository.

  • Allowed values: a string specifying the command to build your static site for production.
  • Required: only if using ssgName: custom, and no netlify.toml configuration file is provided.
  • Default: automatically configured by the framework set in ssgName, but you may want to customize it to your needs.

With our managed hosting, which is enabled by default, Stackbit also takes care to build the website with all production optimizations every time you hit the Publish button in the editor. To customize the command to run, use buildCommand.

Note that Next.js also supports dynamic features such as Server Side Rendering and on-demand image optimization, which require code to run when these are called. This is managed with no further configuration when you use our managed hosting and by external providers such as Netlify and Vercel.

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

This property is used to configure managed hosting and is only used when creating a new project by duplicating a GitHub repository.

  • Allowed values: a string specifying a directory path relative to the project root.
  • Required: only if no netlify.toml configuration file is provided.

The directory where generated static files are stored when the build command completes (see buildCommand property above)

pagesDir

Only relevant when using file content from Git.

  • 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

Only relevant when using file content from Git.

  • 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.5.0
ssgName: nextjs
pagesDir: content
excludePages:
  - internal/**/*
  - README.md

dataDir

Only relevant when using file content from Git.

  • 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

Only relevant when using file content from Git.

  • 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

Only relevant when using file content from Git.

  • 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

Only relevant when using file content from Git.

  • Allowed values: an assets object
  • Required: When using the built-in Git CMS.

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

Relevant when using an external CMS.

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

presetReferenceBehavior: copyReference | duplicateContents

Note that this affects only newly-created presets. Changing this value (or adjusting the exceptions below) have no affect on existing content created from presets.

This is because preset configurations are stored as files and Stackbit will not adjust existing files in your repository.

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.