The preview of your site in Stackbit is generated by the development server of your static-site-generator such as Gatsby or Jekyll. Because the preview is served by the SSG development server, any changes to site's content and code are immediately reflected in the preview. To show you the preview Stackbit runs the development server of your SSG and routes the site pages to your browser.

Running Preview

Stackbit runs the following steps to show you the preview of your site:

  1. It clones your site's repository
  2. It checks-out the preview branch
  3. It installs your site dependencies depending on your static site generator (e.g., npm install for Node based SSGs such as Gatsby and Next.js, and bundle install for Jekyll)
  4. It runs your static site generator's development server (e.g.: gatsby develop for Gatsby, and bundle exec jekyll serve for Jekyll).
  5. It routes any page requests made from your browser to SSG's development server and returns responses back to your browser, as if you are developing your site locally on your local machine.

For example, suppose your site uses Gatsby. In that case, after cloning your repository, checking out the preview branch, and installing dependencies, Stackbit executes gatsby develop in its preview-server to start Gatsby's development server and then routes page requests from your browser to that development server running internally on http://localhost.

Site Preview Diagram

If your site uses Hugo, Stackbit executes hugo server and routes page requests to Hugo's development server running internally on http://localhost.

You can see the logs of how Stackbit pulls your repository, installs dependencies, and runs your SSG's development server by clicking on the "Logs" button in the "Advanced Tools" bottom bar:

Hugo Logs

Preview Updates

Because the preview is served by the SSG development server, any changes to site's content and code are immediately reflected in the preview.

Your SSG's development server should listen to content changes and respond to them by refreshing any opened browser sessions via live-reload or HMR. Most of the static-site-generators have these functionalities enabled by default, so you don’t have to do anything.

Due to the nature of static site generators and how their development server work, any changes made to the code, or the content are immediately picked up by the SSG and reflected in the browser.

Of course, in order for Stackbit to show you the preview of your site, your SSG's development server must work without crashing.

Publishing Changes

When you publish your site, Stackbit merges the preview branch to your master branch.

Note: If you imported an existing site via the import flow, the preview and the master branches might have different names. The branch you have specified as your base branch will be treated as the master branch (even if it isn't called master) and will be used as the starting point for the new preview branch. If the name preview is already taken, the new branch will be suffixed with a short hash preview-qwerty.

Changing the branch where preview or master point to can't be done from the UI at the moment. However, if you happen to need to change this, please let us know and we'll be happy to help you. Also, you can learn more about how the preview branch works in file-based CMS here.