Stackbit v1 is deprecated.
If you have not yet upgraded and wish to do so, please contact support to discuss your options.

Introduction

The new Stackbit is here!

If you have an existing Stackbit site created before December 9th, 2021, this guide has instructions on how we recommend upgrading your site.

A note on existing projects

It is important to note that a project not being editable within Stackbit does not mean that your site is broken. It is still live, and it still works.

If you haven't transferred yet your project's Git repository to your own GitHub account, it is recommended to do so during the transition period, via the Project Settings.

For all live sites that are deployed with Netlify, the live website is already in your own Netlify account.

The Benefits of Upgrading

Upgrading your site means you unlock Stackbit's new visual editing platform. Your editors will be able to make changes to your site in real-time and with the visual context in which those changes will appear on the live site.

You will also receive a code base that makes use of popular open-source tooling and strong, established patterns for modeling content in component-driven websites.

New Stackbit sites are built significantly different than our previous set of themes. To understand how the pieces fit together, see How Stackbit Works and How Themes Work.

Your Code Still Works

Though we would love to see you upgrade your site and unlock the power of the new Stackbit, know that this is not something you have to do.

Your site's code is yours - please ensure that you've transferred the project's code to your GitHub account through the Project Settings. It will still be live through your connected Netlify account. However, it will not be editable through our user interface after the transition period ends.

Upgrade Process

Begin New Project

Visit https://alpha.stackbit.com/create and pick a theme to start from. Choose the scenario that most closely matches your website.

Unlike previous Stackbit themes, the current themes are architecturally very similar. Choosing one is just a starting point. As with existing sites, you'll have full control to customize it.

Set Global Styles

Once you have a new site, use the styles panel to update the basic branding and global styles for your site.

Styles panel on new site

This is a good place to start, as it will help you make stylistic decisions throughout the process.

Migrate Content & Assets

The next step is to migrate content and assets. Like most old Stackbit themes, new projects have a content directory that stores all your content in Markdown files, along with another directory holding images and other visual assets.

You will likely not be able to work through this process entirely in one effort, but will need to bounce back and forth between adding content and functionality. See the next section for adding functional features to your site.

External data sources other than the built-in Git CMS are no longer supported for non-enterprise accounts. If you were storing content in a CMS like Contentful or Sanity, you will need to export and format that content in accordance with the Markdown files found in the content directory.

Add Custom Functionality

Stackbit's new library of components is constantly growing, but it likely doesn't have everything you need to rebuild your site. Here is a guide on adding your own components to a site.

Note that if you are migrating from a React-based framework like Gatsby or Next.js, you may be able to copy existing components and then make the necessary adjustments.

Update Styles

Your new site comes with Tailwind CSS installed and ready to use. This is the recommended method for styling. But you can always import CSS files if you would like. Next.js supports this out of the box. Learn more about styling with Next.js.

Once you're happy with your functionality, round it out by adding styling to match (or improve upon) your existing site.

Common Features

Some things may get lost in the migration. We have a series of common feature guides that may spark something that you forgot to add to the site. Have a look.

Prep for Production

Once you feel like your site is coming together, it'll be time to get ready for deploying it to production. Your new site will already be live, so the only thing left to do is to adjust the DNS settings of your domain name to point to your new website. Learn about connecting a custom domain to your site.

Other Resources

As you're working through this process, you will inevitably have questions along the way. We have a whole new documentation site to help you:

  • How-to guides help you through individual scenarios.
  • References provide full, concise information on annotations, content models, presets, and more.
  • Conceptual guides share more about how all elements of the new Stackbit work.

And if you don't find what you're looking for, join our community and ask for help. Or ask us directly.

Notable Changes

As you migrate content and logic from existing projects, here are the main changes to be aware of:

FAQs

How much effort is involved in upgrading?

That depends on the size and complexity of your site. Sites that didn't make many customizations to behavior from your starting theme may go pretty quickly. Heavily customized sites will take longer.

If you are concerned about the process, join the community and start a conversation.