We're live-coding on Twitch! Join us!

Getting Started with Sanity.io - A Headless CMS You Can Customize

If you're looking for a headless CMS with amazing features and tons of customization, look no further than Sanity.io. I recently migrated my personal site from embedded Markdown files to Sanity, and it's been a great experience so far. So, I figured I would share what I learned with you.

Why I Chose Sanity

After considering many options, I chose Sanity for three reasons.


With Sanity, there's no centralized dashboard. Because of that, you have to manage it yourself, and this has some pretty interesting implications. You get full customization over the dashboard, but you also have the extra responsibility of managing it. More on this to come.


One of my big concerns with Headless CMS options is the jump from free tier to a paid tier. For personal projects, I don't want to pay $50+ per month. Well, with Sanity, they do have a pricing jump, but they also have pay-as-you-go options. If you need more file storage, you can pay just a few bucks a month to add it. Check out the full Sanity pricing.

Side Note: If you want more control over your headless CMS costs, you can look into self-hosting your own headless CMS like WordPress, Ghost, or Strapi.


After looking for advice on Twitter the co-founder of Sanity reached out to offer some clarifications and help. I also had Knut, a developer advocate at Sanity, join me for a series of streams to help through my migration to Sanity. There's nothing more impactful than getting some hands-on assistance from the Sanity team itself!

Creating the Starter Project

To get started with Sanity, we are going to use one of the starter projects. You can find the list of starter projects, here.

I'm personally a fan of Gatsby (static site generator built with React), so in this demo, we will choose "Blog with Gatsby".

To take full advantage of this starter template, log in with both your Github and Netlify accounts. This will allow Sanity to create a new Github repository for you and then deploy the Sanity studio AND the Gatsby site to Netlify.

While many other Headless CMS options will host the dashboard for you, I want to stress again that it's your responsibility to manage the Sanity dashboard. You get full customizability, but you have to deploy/host it yourself. Thankfully, the starter generator took care of the initial deployment to Netlify for you.

With Sanity, it's your responsibility to manage and deploy the dashboard.

Alright, let's look at what Sanity created for us by opening up the Sanity studio.

Click the "Open Sanity Studio" button. You will probably be prompted to log in.

You can remove the getting started sidebar in the studio

Now, look at the `Netlify Sites` section.

Two sites were created. You'll also notice that there are Netlify widgets with each of the sites. These show the current status of the sites. They will originally be in the building state but will update as the builds finish.

Gatsby Site

Once the build has finished, you can open your deployed Gatsby site. Click the link to open your brand new site!

Not too bad eh?

Sanity Studio

The Sanity Studio is also deployed inside of Netlify. This is the site that you are currently viewing. Click on the desk button/logo at the top of the page. Here, you'll see the content creator/editor. Notice there are a few data types created for us in this starter project: blog posts, authors, and categories. We'll take a closer look at these in a bit.

Project Repository in Github

Lastly, the starter project created a repository for us. You can find the link to the repo under the `Project Info` section.

Go ahead and open the repo.

We'll check out the code locally next, but you might have noticed you get some warnings on vulnerabilities. We'll take a look at updating those in a bit as well.

Check out the Source Code

Grab the clone URL and clone the repo to your computer with the following command.

git clone <CLONE_URL>

Then, open it in your favorite text editor, which in my case, is VS Code. Once you get the code open, you'll notice there are two main folders, studio and web. You can probably guess what those correlate to at this point.

To run both of these locally, you'll need to install NPM packages.

Gatsby Project

For the Gatsby app, cd into the web directory and then run npm install.

After that finishes, run npm run dev and you should see that your app has started at localhost:8000. If you open it up, it should look exactly like the deployed app we saw earlier. Although the focus of this article isn't on Gatsby, you have full control over your Gatsby site.

Sanity Studio

For the Sanity studio app, cd into the studio directory and run npm install. After that finishes, run npm run dev. This will start the Sanity studio at localhost:3333. You can open that and see the locally running studio.

Upgrade the Sanity Dashboard

As you saw earlier in the Github repo, you might have some outdated packages. If you do, you'll need to upgrade the Sanity dashboard, which luckily is pretty easy.

Inside of the studio directory, run sanity upgrade to update all of your packages.

After all of that finishes, make sure to run another npm install to ensure that the package.lock.json file gets updated to match the new versions of the packages. I missed this step earlier and learned the hard way.

From there, you can add all of the updates to your master branch and push. This will trigger a new build of your site in Netlify.

Customizing the Schema

Finally, let's take a look at customization. Unlike other Headless CMS options, with Sanity, you get full control over your dashboard including the types of data you work with.

All of your data types are defined in the schemas/documents directory. If you look, you'll see the corresponding schemas for author, category, and post. Go ahead and update the post schema, post.js.

Inside of the fields array is where all of the individual fields for this data type are stored. They typically have the following properties.

  • name
  • type
  • title
  • description

So, to add a new field, it's pretty easy. Just add another object to the fields array. For my blog posts, they often include an embedded YouTube video (like the one above), so I might want to add a link for a YouTube video.

    name:  'videoLink',
    type:  'string',
    title:  'Link for the Video',
    description:  'link for the video'

After doing so, restart the Sanity studio locally (if it wasn't still running) and check out one of your posts. You'll see a new field for the video link!

That's super easy but there are two important things to know. Any time you update your types, you'll need to make sure you deploy the changes to the Sanity GraphQL layer. To do so, run sanity graphql deploy.

Secondly, if you add a completely new data type, you'll need to import that data type into the schema.js file. You can think of this file as being the definition of all of your types in one place. This is the schema that the GraphQL layer uses.

Wrap Up

If you're looking for a new Headless CMS to try out, Sanity is a great one to start with. I love the pricing tier and the customizability, but also the community. The team at Sanity is engaged and extremely helpful.

I'm curious, what CMS options are you using? How do you like it? Let us know in the comments below.

Like this article? Follow @jamesqquick on Twitter