Quick Start
To get started with Stackbit, learn how to provision a new site from a Jamstack theme and edit it. With a theme built on Next.js and Contentful, we’ll show you a few of our favorite features in less than 15 minutes.
Accounts
Sign up for accounts at Stackbit, GitHub, Netlify, and Contentful.
Head to Account Settings and connect your Stackbit account to GitHub, Netlify, and Contentful:
- Next to GitHub, click Connect, then Authorize Stackbit App (popup).
- Next to GitHub, click Configure, then Install (popup).
- Next to Netlify, click Connect, then Authorize (popup).
- Next to Contentful, click Connect, then Authorize (popup).
Provision a new web site
- Spin up a site in Stackbit from our demo theme. You’ll land on the Stackbit Site Builder with the correct GitHub repository already filled in under Theme.
- At the top of the Stackbit Site Builder screen, change your project name from the random words generated by Stackbit to
My Site
. - Under Headless CMS, select the Contentful Organization where Stackbit should create a new Contentful Space.
💡 Tip: If you receive a “Selected organization on Contentful is out of available space” error, click Solve on Contentful and create a new Organization in your Contentful account (or delete an old Space from an organization), then come back and click Retry.
Contentful free plans receive one Space per Organization, but may have more than one active Organization.
However, Organizations cannot be easily deleted or renamed, so you may find it tidier to delete unneeded Spaces from existing Contentful Organizations.
- Under Repository, if you’d like to change the account under which Stackbit should create a new repository or set its visibility to private, click Expand to configure Github and choose the appropriate settings.
- Click Create Site.
⌛ What Stackbit Site Builder does while you wait:
- Creates a new GitHub repository by cloning the original repository into your GitHub account, creating a
preview
branch for it as well. - Creates a new Contentful Space and provisions that Space with initial content from the
export.json
file in the original repository. - Creates a Netlify site. (Deployment to Azure and Digital Ocean are also available, but full features are still under development.)
- Creates webhooks between Contentful and Netlify so that whenever something is published in Contentful, it will trigger a deploy in Netlify.
- Creates webhooks between GitHub and Netlify so that whenever something is committed into GitHub, it will trigger a deploy in Netlify.
Live preview out of the box
Stackbit Studio renders a live preview of your site by hosting the same fast-responding technology you’d rely on for localhost development, providing you with a smooth editing experience in the cloud.
Simultaneous CMS edits
Once your site is up and running in Stackbit Studio, you can edit the content visually.
- Click Content in the top navigation bar.
- Within the site’s preview panel, hover over the
This Is A Big Hero Headline
and click it (or expand Sections > This Is A Big Hero Headline > Title in the sidebar). - Change the copy to
Welcome to my site
and click outside of the editing box to save your work.
This change immediately synchronizes with Contentful. To see that the change in Stackbit propagated to Contentful:
- Click the gear icon in the top left corner of Stackbit Studio.
- Below the project name, in Connected Services, in the Contentful card, click Open.
- Click Content in Contentful’s top navigation menu.
- Find and click on the Flexible Page-typed item named Home in the table.
- In the home page’s Sections repeater field, the first entry has a type of Section: Hero. (Also note that it has a status of Changed rather than Published.) Click it.
You’ll see Welcome to my site
in the hero section’s Title field.
This sync works both ways. Let’s test that.
- Beneath the hero section’s Title field in Contentful is the Subtitle field. Change the Subtitle from “lorem ipsum” text to
This change came from Contentful
and click Close. - Navigate back to the browser tab where you have your site open in Stackbit Studio. (Note: You don’t need to click ‘Publish’ in Contentful.)
- Close the Settings modal.
You’ll see This change came from Contentful
in the subtitle area of the home page within Stackbit Studio’s preview panel.
Live sharing
- From the Share menu in Stackbit Studio’s navigation bar, open your live preview on your smartphone with the QR code. Alternatively, click Copy Link and send it to yourself to open on another device.
- In Stackbit Studio, change the home page’s hero title from
Welcome to my site
toWatch the title change
and click outside of the editing box to save your work.
Within a few seconds, you’ll see the update appear on your smartphone.
💡 Live sharing has no dependencies on authentication or local networks – it works the same in a second browser tab or on the other side of the world.
Live sharing works as well with traditional static site generators like Jekyll and Hugo as it does with hydrating SSGs like Gatsby and Next.js. If your theme live-previews on localhost, it will live-preview in Stackbit Studio and Stackbit Live Sharing.
Preview code changes
Online with VSCode
You can edit your theme’s codebase directly within the Stackbit Studio while previewing the impacts it makes visually.
- Click on Code in the top navigation bar.
- In the panel that expands at left, click Code Editor to expose an integrated VSCode editor.
- Expand
src/templates
and clickflexible-page.jsx
. - Find the
h1
tag and, in itsclassName
, changetext-gray-900
totext-pink-700
and click File > Save in the VSCode editor (or Ctrl+S on your keyboard).
The word “Home” will flip to magenta in the home page preview at right, as will the word “Contact” if you navigate to that page.
💡 Tip: After VSCode’s first use, which warms it up, you can open flexible-page.jsx
and jump straight to the <h1>
tag by hovering over Home
in the preview panel and clicking Code in the component’s lower right-hand corner.
Through Git
Your live preview in Stackbit Studio is driven by the preview
branch of the GitHub repository that Stackbit provisioned for you.
The VSCode editor in Stackbit Studio is a convenient way to edit preview
, but you can just as easily edit it using your favorite local development tools.
- Clone
my-site.git
from GitHub to your local machinegit clone https://[email protected]/YOUR_USERNAME/my-site.git
- Switch your local machine to the
preview
branchcd my-site git checkout preview
- In your favorite IDE, find and replace every occurrence of
-azimuth-blue
with-purple
under./src
- Stage, commit, and push the changes from your local machine to GitHub
git add --all git commit -m "Color change" git push
Within a few seconds, back in Stackbit Studio, you’ll see -purple
throughout your codebase in VSCode, and a purple-themed site in the preview panel.
💡 Any colleagues following along from a smartphone on live sharing will also see the site turn purple.
Drag-and-drop components
Be sure to try adding, deleting, and reordering items within list-repeater components such as page sections and call to action buttons.
- To reorder items or to create the first item in an empty list, use the content sidebar.
- To delete or add additional items, you can use either the sidebar or on-page editing.
💡 With a visual editor like Stackbit, one of the biggest productivity boosts theme developers can give content authors is a well-componentized landing page builder. Check out our tips for refactoring an existing theme.
We’re big believers that great themes make great teams, so you’ll find plenty of examples in our open-source starters.
Lightweight configuration
For all of this to work, Stackbit only requires one edit to your theme’s codebase: a stackbit.yaml
file.
(Unless you want to incorporate one of Stackbit’s useful tools into a new theme, like Sourcebit, which can help you connect a headless CMS to an older SSG like Jekyll).
Here is the stackbit.yaml
for the starter you’ve been using:
# The stackbit.yaml file lets you define the characteristic of your website needed to make your theme, or project, work with Stackbit. For more info about stackbit.yaml configuration visit https://www.stackbit.com/docs/stackbit-yaml/
stackbitVersion: ~0.3.0
nodeVersion: 14
ssgName: gatsby
cmsName: contentful
# The "buildCommand" and the "publishDir" properties are used to configure the serverless deployment platform when Stackbit creates a new site from this theme.
buildCommand: npm run build
publishDir: public
# The "import" object defines how Stackbit should provision Contentful when creating a new site from this theme via https://app.stackbit.com/create.
import:
type: contentful
contentFile: contentful/export.json
spaceIdEnvVar: CONTENTFUL_SPACE_ID
accessTokenEnvVar: CONTENTFUL_ACCESS_TOKEN
# To allow creating and duplicating pages in Stackbit Studio, as well as other advanced editing capabilities, specify which models describe your website pages and specify their "urlPath" patterns. The urlPath should have the same logic used in createPage in gatsby-node.js and in Contentful API names.
models:
flexible-page:
type: page
urlPath: '/{slug}'
post:
type: page
urlPath: '/blog/{slug}'
Stackbit configuration is minimal and flexible.
stackbitVersion
makes sure you’re taking advantage of the features you expect.nodeVersion
is optional, if your theme needs a different one than Stackbit’s default.ssgName
andcmsName
to specify Gatsby + ContentfulbuildCommand
andpublishDir
if you’re doing anything out of the ordinary for your SSG.import
so Stackbit can provision a schema and starter content in Contentful when creating a new site.models
, which helps Stackbit Studio understand relationship between data items that your SSG turns into pages, and their URL paths. This lets Stackbit Studio present you a picklist of page types under Add page > Create Page > Choose a template, and ensures that after you click Create, Stackbit Studio redirects you to the correct preview URL.- Stackbit Studio infers each site’s content model according to its CMS (API calls for Contentful,
schema.js
for Sanity,config.yml
for Netlify CMS…). - If you don’t have a CMS at all, you can use more verbose options in
stackbit.yaml
to define one, which you can do from Stackbit Studio’s point-and-click content modeling tool. Be sure to optimize SEO metadata editing.
- Stackbit Studio infers each site’s content model according to its CMS (API calls for Contentful,
Production at your fingertips
From the Publish menu in Stackbit Studio’s navigation bar, the Live Site button will open your production web site in a new tab, and the Publish button will:
- perform a pull request from your GitHub repository’s
preview
branch to itsmain
ormaster
branch - publish any unpublished API-based CMS content (with granular scoping to a given page’s content, as well as scheduled publishing, available on paid plans).
Next steps
- Explore Stackbit Studio Settings by clicking the gear icon in the top left corner. There are advanced goodies for setting the runnable directory of a theme in a monorepo, adding extra environment variables your theme may need during live preview, and more.
- Now that you’ve learned to provision a new site with Stackbit, read how to import an existing site. With a
stackbit.yaml
file in place, a running site will work the same in Stackbit Studio whether you let Stackbit provision it or whether you imported it into Stackbit. When you import an existing site, you’ll need to set up a few webhooks yourself that Stackbit would have provisioned for a new site. - Download our CLI tool to speed up development.
- Check out the rest of our documentation for more tips and tricks.