Introduction

When you create a new project based on one of our themes, the contents of the selected theme are copied into your project and serve as the basis for your new website. At that point, control is handed over to you.

Before you start shaping this new project into truly your website, it's important to cover how the theme is wired up.

It is the theme that brings all elements together: configuration, content, presets, Site Generator framework, CSS framework and components.

It defines how to process requests to render URLs and delegates rendering work down to components. There is no other magic behind the scenes that gets pages rendered.

Let's start by identifying the main elements of a theme. To follow this guide, we recommend that you look at the actual code as we discuss specific specific files and directories. You can either:

  • Create a new project based on one of our themes and use the online code editor to look at files,
  • Clone the project locally and load it in your preferred editor, or -
  • Look at theme contents on GitHub, e.g. the Small Business theme.

Congratulations, it's a Stackbit Project

The first thing to note is the unassuming stackbit.yaml at the root directory of your project.

It provides Stackbit with the basic details on how this project is constructed: which framework is used (Next.js), which CMS is used (Git), where to look for content files and store new ones, URL mapping a more. We'll touch on most of these in this guide.

It's not a complex file: most properties have sensible defaults and don't need to be explicitly set. There is of course a full reference to this file.

It's Based on Next.js

If you're not familiar with Next.js, it's highly recommended to go through their official tutorial.

Your project is organized as a standard Next.js website:

  • package.json declares needed dependencies and scripts
  • Assets are in the public directory.
  • Page routes are in src/pages. We'll get back to these later.
  • Next and Webpack configuration are found in next.config.js.

Right at the top of next.config.js something notable happens: the sourcebit package is initialized and fetches all content. Sourcebit is configured via the file sourcebit.js in your project:

const sourcebit = require('sourcebit')
const sourcebitConfig = require('./sourcebit.js')

// ...
sourcebit.fetch(sourcebitConfig)
// ...

Websites created with Stackbit are typically statically-generated in full or at least in part. This is why all content is fetched right when the code starts running - we need it in order to determine which pages should be generated, and have their data in hand. However, this behavior is highly customizable to your needs.

We will get back to sourcebit.js in more detail later. Before we do, let's move on to look at how styling works in themes.

Next up: How Themes are Styled