Skip to content

Setting up gatsby-theme-catalyst-sanity

gatsby-theme-catalyst-sanity is a “core” theme for integrating SANITY.io into Gatsby Theme Catalyst. This means it focuses on function and utility with minimal visual styles. It is designed as a jumping off point for further customization and development work before being deployed. SANITY.io is a headless CMS that provides a GUI for content authoring and data entry - meaning your clients/users are not editing markdown.

This tutorial assumes you have basic familiarity with Gatsby and modern web development practices.

Install the theme using a starter

# create a new Gatsby site using the starter site
gatsby new catalyst-sanity https://github.com/ehowey/gatsby-starter-catalyst-sanity

Install SANITY.io

npm install -g @sanity/cli

Initialize SANITY.io and setup your content studio

# Move to the starter directory
cd catalyst-sanity
# Move to the content studio directory
cd sanity-studio
# Initialize SANITY
sanity init
# Answer YES to reconfiguring the studio
? The current folder contains a configured Sanity studio. Would you like to reconfigure it? Y
# Register or login to SANITY following their prompts
Good stuff, you are now authenticated. You will need a project to keep your
datasets and collaborators safe and snug.
# Create a new SANITY project
? Select project to use (Use arrow keys)
❯ Create new project
# Give your project a name
? Your project name: Catalyst
# Use the default dataset configuration
? Use the default dataset configuration? (Y/n) Y
# Import starter dataset, select "production" dataset when prompted
cd data
sanity dataset import production.tar.gz
# Deploy the graphql schema
cd ..
sanity graphql deploy
# Start your studio on a localhost
sanity start
Content Studio successfully compiled! Go to http://localhost:3333

Congratulations! You should be looking at the new backend for your website! You can update data now or just leave it for later.

Update sanityProjectId

In order to properly source your data you need to update the theme options for gatsby-theme-catalyst-sanity to give it the correct project id. The easiest way to do this is to open sanity-studio/sanity.json and at the top of the file you should see the project id like this:

// In sanity.json
  "api": {
    "projectId": "c1x70rzt", // This is what you need
    "dataset": "production"
  },

Now open gatsby-config.js and update the theme option with the correct project id like this:

{
      resolve: `gatsby-theme-catalyst-sanity`,
      options: {
        sanityProjectId: `c1x70rzt`, // Change this line
      },
    },

You can also do this using environment variables, if you setup a private dataset with a token you need to use environment variables to ensure it is not committed to your version control.

Run ‘gatsby develop’ for the first time

Now that you have the content studio setup you are ready to fire up your site for the first time! Because of how SANITY.io is integrated it is normal for you to see some warnings in your console log about GraphQL queries, these are warnings only and not errors.

# Get back to your root directory from /sanity-studio
cd ..
# gatsby develop to start your development server
gatsby develop

Nice work you did it! You can remove the folder /sanity-studio/data you don’t need it anymore. And committing it to your git repo is unnecessary.

Experiment with theme options to control building pages

gatsby-theme-catalyst-sanity was designed as a “core” theme with a number of different theme options to control the createPages API. This means that you can enable/disable certain functionality for your end user without having to create a custom content studio.

For example - if you want to disable and turn off the blog you would do the following. In gatsby-config.js:

{
      resolve: `gatsby-theme-catalyst-sanity`,
      options: {
        // Example for an env variable
        // sanityProjectId: process.env.SANITY_PROJECT_ID,
        // sanityDataset: process.env.SANITY_DATASET,
        // sanityToken: process.env.SANITY_TOKEN,
        //
        // Default options are:
        // sanityProjectId: "abc123" // Required
        // sanityDataset: "production"
        // sanityToken: null
        // sanityWatchMode: true
        // sanityOverlayDrafts: false // Token is required for this
        // sanityCreatePages: true
        sanityCreatePosts: false,
        sanityCreatePostsList: false,
        // sanityCreateProjects: true
        // sanityCreateProjectsList: true
        // sanityPostPath: "/posts"
        // sanityProjectPath: "/projects"
        // useSanityTheme: false // Experimental right now
        sanityProjectId: "p9a6h8j1",
      },
    },

In sanity-studio/structure/deskStructure.js remove these lines to hide the posts GUI:

S.listItem()
  .title("Posts")
  .child(S.documentTypeList("post").title("Posts")),

Remove any links or references to the post pages and presto - no more blog.

If you see an error when you try to navigate to the posts index or a post page you need to run gatsby clean - because of the cached pages it can throw this error: Error: EnsureResources was not able to find resources for path: "/posts"

Try playing around with a few of the different theme options to see what you can make happen.

Deploy the content studio

Right now the content studio is only locally deployed, which means you can change it from your computer however if you run sanity deploy inside of catalyst-writer/sanity-studio you can deploy it to a https://studio-name.sanity.studio domain for free making it accessible remotely.

Explore the SANITY.io content studio and add your own data

The dataset you imported comes with placeholder data to get you started. Play around with the data and see what happens. You should see live updates on your local site in development mode because of real time previews with watch mode. You may occassionally need to restart the Gatsby development server (gatsby develop) to see certain changes.

Push to GitHub and deploy your site

There are a few different ways to do this and publish your website. This is what works best for me:

  1. Push your files to a new GitHub repository
  2. Build and Deploy with Netlify

Setup a webhook to automatically redeploy when content updates

Because your content is separate from the git repository you will need a webhook to ensure your site redeploys when the content in SANITY changes. Both Netlify and Gatsby have good information in their docs about using webhooks.

# Get back to your sanity folder
cd sanity-studio
# Setup the webhook, e.g. is for Netlify
sanity hook create
? Hook name: netlify
? Select dataset hook should apply to: <yourDataset>
? Hook URL: https://api.netlify.com/build_hooks/<someId>

Setup siteUrl in gatsby-config.js

Most site metadata is generated from SANITY however generating both robots.txt and sitemap.xml depend on a properly defined siteUrl field found in gatsby-config.js. There is also a field for this in your Site Settings within SANITY, you need to fill these both in.

module.exports = {
  siteMetadata: {
    siteUrl: `https://www.example.com`, //Change to you site address, required for sitemap.xml and robots.txt file among other things
    ],
  },
}

Next steps

You can use this theme as a starting point for creating your own custom SANITY.io and Gatsby site. To see an example of how this is done you can look at the source code for gatsby-theme-catalyst-hydrogen as this will show you an example of layering a presentation theme on top of the data theme.

I would love to hear about your results and see what you create!

© 2021 Gatsby Theme Catalyst