Keystatic

We’re using Keystatic CMS as a headless CMS for posts and pages, which is a git-based content management system.

You can access your site’s CMS on the /keystatic path.

We chose keystatic because it’s handy, easy to configure and gives you a convenient method to handle content while keeping elements of the site separate.

Setup

There are a few methods you can use to set up Keystatic, we’ve configured the keystatic.config.ts file for both local and cloud mode so we’ll start with those.

Local Mode

Most projects start their lifecycle with Keystatic in local storage mode:

keystatic.config.ts

export default config({
   storage: {
      kind: 'local'
   }
})

Content is stored on your local file system directly, and this is what makes the most sense when starting a project.

Keystatic cloud

Full Details here

Keystatic Cloud simplifies authentication (GitHub) with your projects. No need to deal with environment variables and a custom GitHub app.

Keystatic Cloud also offers opt-in products such as Cloud Images (an image storage, optimisation and delivery service) or multi-player editing.

Configuring your project with Keystatic Cloud In your Keystatic config, you’ll need to set the storage option to cloud.

You’ll also need to add the cloud.project property with the name of the team and project from your Keystatic Cloud account:

keystatic.config.ts

import { config } from '@keystatic/core'

export default config({
  storage: {
    kind: 'cloud',
  },
  cloud: {
    project: '[TEAM_NAME]/[PROJECT_NAME]',
  },
  ...
})

Each project in Keystatic Cloud has a settings page where you’ll find a ready-to-paste code snippet in your config file, Saas Wind is already configured for either local or cloud.

Finally, there is Github Mode…

Github Mode

Full details here.

Keystatic’s github mode unleashes enhanced collaboration capabilities.

To use it, you’ll need your project on an existing GitHub repository. Collaborators will need write access to this repository.

Setting up GitHub mode

Start by changing the storage option in your Keystatic config to use the github kind.

You will need to specifiy a repo owner and name:

keystatic.config.ts

storage: {
   kind: 'local',
   kind: 'github',
   repo: {
     owner: REPO_OWNER,
     name: REPO_NAME
   }
}

You can also define the repo as a string with the owner/name format:

keystatic.config.ts

storage: {
   kind: 'github',
   repo: `${REPO_OWNER}/${REPO_NAME}`
}

Connecting with GitHub

With github mode on, visit the /keystatic route. You will be prompted to login with GitHub.

The first time you click this button will initiate the setup process:

If you happen to know the URL of your deployed project and/or the GitHub repo is owned by a GitHub organization, you can fill in those fields.

Otherwise, leave them blank and click on “Create GitHub App”.

Create a custom GitHub App

The next step will walk you through creating a GitHub App. Choose a name for your app, and proceed.

Grant repo access

Next, you will need to grant this new GitHub App access to your GitHub repo:

Finally, you will be taken back to your local Keystatic Admin UI… running in github mode!

👀 You can tell Keystatic runs in github mode by the extra UI around your GitHub repo, like a branch dropdown.

New environment variables

Behind the scenes, some environment variables were generated in a .env file on your project:

# Keystatic
KEYSTATIC_GITHUB_CLIENT_ID=...
KEYSTATIC_GITHUB_CLIENT_SECRET=...
KEYSTATIC_SECRET=...
NEXT_PUBLIC_KEYSTATIC_GITHUB_APP_SLUG=...

These variables are used to authenticate users with GitHub, based on their access to the GitHub repo in question.

Next time someone with write access on the repo visits /keystatic, they will be able to login and access the Admin UI.

Branch prefix

The branchPrefix option lets you scope out what GitHub branches Keystatic should interact with:

keystatic.config.ts

storage: {
   kind: 'github',
   repo: 'Thinkmill/keystatic',
   branchPrefix: 'my-prefix/'
}

Keystatic will only list branches starting with my-prefix/ in the Admin UI, and will only let you create new branches with that prefix.

---

Editing schema

keystatic.config.ts is the heart of the keystatic setup and has the following already added:

Pages

Pages are non-posts, for example the about page, services page, privacy policy, etc would all go here.

Posts

Posts handle the blog of the site.

Themes

Themes are json files that continue the look and feel of your project, and are easy to modify

Settings

Settings lets you change navigation, identity, links, etc

Homepage

This is where you can customize your project’s homepage from the hero, to the features to the call to action at the bottom.

If you want to change how these are configured, you can do it from inside the keystatic.config.ts file and test locally before deploying.

Once you deploy your site, you can log into your keystatic page and make changes to your site that way, these changes then get pushed to GitHub and deploy via Vercel (or where ever you chose to host your site).