Starting points

There are a few ways to get started with Stackbit.
Not all of them require creating an online Stackbit project from the get-go.

Stackbit projects & Local Development

When you create a project via the Stackbit UI, we run your site's code inside a container in an editable live preview, enabling multiple users to create and publish content. You control which branch is used to run code and what content is loaded.

However, for developers wanting to evaluate or work on Stackbit-enabled sites, our strong recommendation is to work locally on your machine - where you have your favorite tools and the best visibility. When working locally, a Stackbit project is not needed until you want to share your work with others. Learn more.

Here's how we recommend you get started, based on your needs:

A. Learning Stackbit as a developer

It's best to start with a minimal website on your local machine and follow our Getting Started tutorial. Simply run: npx create-stackbit-app@latest.

The tutorial will instruct you how to use local development mode, in which you do not need a project created through our UI. Once ready to share your work with content editors and other collaborators, though, you will need a project: see Use my repository.

Another popular way to learn is by example. You can either:

  • Run npx create-stackbit-app@latest --help for a list of curated starters & examples that you can easily create from the command line, or:
  • Pick any repository on GitHub that is Stackbit-enabled, and clone it locally, or create an online Stackbit project for it using Duplicate a repository.

Our official examples are found here.

B. Adding Stackbit to your existing website

If you're not building or re-building a website from scratch:

Take a bit of time to go through the Getting Started tutorial and explore the codebase locally. Then, follow our guides:

  1. A minimalist guide to adding Stackbit. Does not require a CMS.
  2. Adding Stackbit to a Next.js + Contentful Project

Once you have basic Stackbit support working on your local machine, create an online project so you can invite collaborators & content editors - see Use my repository.

C. Evaluating Stackbit as a content creator

To experience content creation with Stackbit, quickly create a project from any of our starters. No dev skills are needed.

D. Advanced usage

You can create multiple Stackbit projects over the same GitHub repository but with different project settings, code branches, or CMS configurations. This opens up a variety of use cases. Learn more.

The Create from GitHub screen

To create a Stackbit project for an existing repository, open Create from GitHub.

Prerequisite: the repository should have a valid stackbit.yaml configuration file (reference). To add this configuration to an existing codebase, see above.

First, specify your need:

Create from GitHub - Step 1

"Use my repository"

In this mode, the created Stackbit project will directly use the specified repository:

  • Any code changes you make to the branch that content editors are using (typically, the preview branch) will be reflected immediately in the Stackbit project.
  • If you store your content as files in the same repository rather than a headless CMS, any edits made with the visual editor will be committed back to the editors' working branch in this repository.
  • Users with Owner or Developer permissions for that Stackbit project can edit the repository's code using the built-in code editor.

If your site is using a headless CMS as a content source (as defined in the stackbit.yaml configuration file), you will be prompted to connect Stackbit to the relevant CMS and select an existing space/dataset/environment to connect to (the terminology depends on the CMS).

In this mode, Stackbit needs write permissions to the repository. You will be prompted to install our GitHub app and then confirm the required permissions. Then, you will only be able to choose from among the repositories you've granted Stackbit the needed permissions for.

Use my repository - Repository selection step

Needed permissions

To run correctly over your repository, Stackbit needs the ability to commit & merge code, create branches and add a webhook. To grant Stackbit these permissions for a repository, you need to have these rights yourself - which requires you to have Admin-level permissions in GitHub for that repository.

You should have these permissions if either of the following applies:

  • You have an Owner role in the GitHub organization the repository is under.
  • You or your GitHub team have been granted Admin-level access to a specific repository by an organization owner / repository-level Admin user.
  • The repository is under your personal GitHub account.

Note: in the Stackbit visual editor, users will only be able to perform actions matching their defined role in that Stackbit project. It's encouraged to avoid giving users full permissions when not strictly needed.

Note: setting-up a GitHub app is a two-step process: first, you install the app.
At this stage, you haven't yet granted it any permissions. Then, you configure for which accounts and/or specific repositories it is granted access. Make sure you complete both steps when the GitHub app install window pops up.

Configuring branches for existing repositories

The target and working branches will be automatically configured for you, though you can make adjustments as needed. Learn more about customizing Git branches.

Note: you can tweak the branch configuration either during project creation or later from the Project Settings. However, do verify you're working with the correct branches before starting to edit and publish content.

Multiple projects with one repository

There are various use cases in which you'll want to create more than one project over the same code repository:

Case 1: Creating an intermediary QA environment

Imagine the following scenario:

  • Content editors use the visual editor, which is running the default preview branch.
  • Developers are working locally in feature branches, and when they're ready - merge and push their changes into preview.
  • From time to time, developers push a change that breaks something, sometimes making content editors unable to work until the issue is fixed.

To improve quality, you'd want to have an intermediary environment where all code changes considered "ready to deploy" by developers can be reviewed easily by content editors (or dedicated QA) before they give their ok.

To implement this:

Assuming your normally-configured project is called "awesome-site",

  1. Create a new branch in your repository, e.g. qa (or acceptance, or whatever else you'd like to call it).
  2. Using the Create from Github screen in "Use my repository" mode, create a new project with preview as the target branch and qa as the working branch. Let's call this project "awesome-site (QA)".
  3. Developers would merge their code from feature branches into qa.
  4. Anyone who was given access to the new "awesome-site (QA)" Stackbit project can then review what's in qa.
  5. Users with an Owner or Developer role for that project will be able to merge to preview straight from the visual editor (or you could do it on GitHub).
  6. Once these changes are merged, editors get them in the "awesome-site" project which they use to edit content for production.

As for content: if your project uses a headless CMS, you can decide whether to have this project connect to the same CMS space (a.k.a dataset or environment, depending on the CMS) or use a different one as part of the project creation wizard.

Case 2: Multiple websites using the same CMS space

If your company manages multiple domains, e.g. a dedicated site for each brand or product line, you may prefer to use just one CMS space (environment) to manage all these sites, since:

  • This ensures the content model is consistent for all sites
  • Shared content is easy to consume and refer to
  • Plus, having an extra site would not mean an extra CMS space you'd need to pay for.

Typically, however, using one space makes it harder and more error-prone to navigate or edit content within the CMS - since content for all sites will be visible to everyone all the time. This forces organizations to manage multiple spaces, complicating pricing and possibly maintenance as well.

Instead, you can use multiple Stackbit projects:

  1. Create multiple projects via "Use my repository" mode, over the same repository. You may use either the very same branch for all, or gradually roll out code updates between sites via multiple branches.
  2. Using Project Settings, define environment variables for each project which your code will use to load only the relevant content for a specific website.

Easier said than done? to achieve full isolation of content between the sites, talk to us and we'll help you design a solution that fits your needs and your stack.

Case 3: A website with multiple locales

It is also possible to use multiple projects which have a limited view into parts of the same website. Each project can be set up for editing and reviewing content for a single locale only (e.g. en, fr-ca, etc.). Talk to us about to best enable this for your needs.

"Duplicate a repository"

In this mode, you can bring in the URL of any GitHub repository you have read access to. Stackbit will duplicate that repository, and the project will be based on the duplicate.

Duplicate a repository

This is a good way to take any Stackbit-enabled example or starter that you find on GitHub and take it for a spin, without needing a local development environment. You can also transfer the new repository to your own GitHub account.

When you specify a repository URL, Stackbit by default will pick the repository's default branch (e.g. main, master) as the basis from which it will create two branches in the duplicate repo:

  • The Working Branch is the one our visual editor will run for content editors to work with. This branch will be named preview.

  • The Target Branch is for your live production site (when using our default hosting). It will be named either main or master. This is the branch we will deploy your live site with.

You can later change this configuration at any time using the Project Settings screen.

Transferring to your GitHub account

To own the code behind your new project, you'll want to have the duplicate repository under your own GitHub account, or under a GitHub organization that you own. This will allow you to clone its contents to your local machine, push changes, modify branches, and so on.

To initiate the transfer, use the Project Settings screen (after the project is created). You can later rename or move the repository as you wish and Stackbit will update automatically.

Importing content to CMS

Some example repositories are configured to use a headless CMS, e.g. our Contentful-based minimal starter. For these examples to function, your CMS account needs to be bootstrapped with the proper content model & initial content.

When you duplicate any of our existing CMS-powered examples, this data will be imported automatically for you. All you need to do is connect Stackbit to your CMS account when prompted, and we will create and initialize a new space/dataset. This will not conflict with any other content in your CMS.

If you want to create an example repository that others can duplicate, take a look behind the scenes at the import attribute in stackbit.yaml (e.g. here).

Advanced options

Site root directory

Usually, the stackbit.yaml configuration file and the web framework's home directory (where you'll find the package.json file and other framework-specific files) are found at the root of the repository.

If that is not the case, you can specify a different root directory right after you pick a repository. Typically, the first attempt to validate the chosen repository would fail, because it looks at the root directory. You can then provide a non-default value and re-validate.

If you have a more complex monorepo layout and are unsure how to bring it into Stackbit, talk to us!

Creating projects under a Stackbit organization

Customers of our paid plans have an organization entity in Stackbit, through which permissions and projects are centrally managed.

To create a new project under your organization, you need to have admin rights to it. You will see the option to create the project either under your organization or in your personal account.

Opting in or out of managed hosting

When duplicating a repository, your new project will come with managed hosting enabled by default. This makes it easy to evaluate starters & examples with a live website to publish to. You can turn it off in the project settings.

However, in Use my repository mode, we do not automatically enable managed hosting.

It is typical in this mode to have multiple projects over the same code repository which are deployed in a customer-specific fashion, without necessarily using our managed hosting. You can however enable managed hosting at any time from the project settings.