Connect to GitHub with Vercel

You'll be prompted to go through a few steps. You can read the step by step walkthrough below for details, but here's a visual representation of the mostly automated journey you'll be taken on:

Start by visiting the following URL: https://keystatic.com

Select one of the starter templates:

You'll be prompted to tell us about yourself. This is optional, but it helps us understand who is using Keystatic and how we can make it better.

After that, you'll be taken to Vercel's project starter dashboard, where you'll be prompted to create a new GIT repo based on the template you've selected in the previous step:

Change the GitHub scope and repo name if needed, and click the create button.

You will then be prompted to add an integration:

Click Add. You may need to authenticate with GitHub if you have 2FA turned on:

You'll be prompted to create a new GitHub App:

When you do so, you'll be redirected back to the Vercel project starter, and you'll see your new project being deployed 🎉

Once the project is deployed, you will be prompted to install the GitHub App you've created.

Click Install & Authorize.

Aaaaannnnd… Here comes Keystatic! ✨

At this point, you're all setup with a fully deployed project using Keystatic. You can start creating, editing and deleting content.

Chances are you want to work on your project locally though. Let's get you setup on your machine.

First, clone the GitHub repo you've just created:

Move into your cloned repo, and run npm install to add the dependencies:

If you try running the project with npm run dev and visit the /keystatic URL, you'll find out you're missing some required environment variables:

Why did that not happen on the remote?

Well, behind the scenes, those variables were created and added to the Vercel project.

Check this out:

If you open up your local project with your code editor of choice and check the .env file, you'll see… it's empty:

Copy the environment variables from the Development environment from Vercel:

When you're done, your .env file should look like this:

Congratulations! ✨

At this point, you're all setup locally and remotely. You just need to make sure that your project runs on port 3000.

Have a play with Keystatic and let us know what you think!

Here's a mini challenge to get you started.

The keystatic.tsx file is where we define Keystatic's content schema. You can see that right now, we have a collection of posts setup:

It's set to generate content in content/posts, and if you look at the schema object, you'll see fields defined for a title, slug, contentand authors:

Surprise surprise, if you go in the Keystatic Admin UI and create a new post, those are the exact fields you can see:

Just for fun, add a new field to the posts' schema. Anything you'd like to try!

Actually, the TypeScript autocompletion makes is super easy to see what's available.

Choose a new field name, type fields. and you should be presented with some choices:

Here I'll choose checkbox, but feel free to try something else! I'll add a required label too:

When you're done, hit save and head back to the browser and look at what happened:

Oh, look! A new opt-in checkbox 🎉

Notice on the top left that you're on the main branch. When you create the post, it will merge it directly to your main branch!

Instead, create a new branch from the menu next to the branch dropdown:

You are now on the test branch, and you can even see a new option to create a Pull Request!

Okay, fill up the new post form with some content, and hit create:

You've just created a commit in the test branch on the GitHub remote!

Go check! But actually, it's even more rewarding to create a PR from the Admin UI:

Yep - you can see a new PR form on GitHub.

Scroll down, and see the changes made to the codebase:

The new post is being created in content/posts, just like we defined in the config.ts.

You can't see these code changes locally, they're only on the remote so far.

You can pull the test branch, or create and merge that new PR and pull from main:

After pulling, you'll see the new content/posts folder in your local project:

Nicely done!

We hope this onboarding guide was useful ❤️

We're building Keystatic in the open as part of Thinkmill Labs Research & Development.

Feedback on how we're going, what you're looking for, and what you'd like to see next is super helpful as we progress!

You can do so publicly in our GitHub discussions, but if you want to reach out privately, you can use the “Send us a message” button at the bottom of the Keystatic website.

Thank you so much! 🙏