😎 Discover cool tips and tricks for customization in our next Developer Deep Dive virtual event - sign up now!

Creating a 1-click Sanity Starter Project

In this guide, we'll take an existing studio and front end and turn it into a 1-click Starter project. We can re-use this Starter for our own purposes, share it with the community, or even submit it to be included as a featured Starter on sanity.io/create

Key concepts for Starter creation

  • Restructuring a project into proper directories
  • Creation of metadata inside sanity-template.json
  • Testing locally with sanity-template CLI
  • Seeding the Starter with data
  • Future-proof the Starter with renovatebot

Prerequisites

  • General knowledge of Sanity
  • Knowledge of NPM scripts
  • Working knowledge of the shell and CLIs

Getting Started

We can create a Starter that includes just a Studio or just a frontend. We can also create a Starter that contains both, or even multiple studios and frontends.


In this guide, we'll start with a basic clean Studio and a basic frontend that prints JSON data from the Studio. If you want to follow along with the guide, you can get the code by using this starter.

Clone the created repository and you'll have a directory with a folder named web and a folder named studio. If you want to follow along with your own starter, you can skip this step.

Gotcha

At this point, you'll want to start this as a new Git repository. You can do this by running rm -rf .git in the repository and then initializing a new repository with git init. We do this to have a cleaner history and an easier way to rename our repository to match what the Starter code is expecting.

Structuring your project


A Starter project follows a specific structure. We need to reorganize our code to follow that structure.
PROTIPRead the full Starter documentation to see more details on structuring a Starter.


Currently, our website and our Studio live in directories at the root of our project. We need to move them into a directory called template. The template directory contains all the information that is created when a developer clicks "Create."

Protip

This directory should usually contain a README file with project instructions, as well as any pertinent links. You can also initialize an NPM project and install any tools (such as Lerna), which can make running the entire project easier.


Let's go ahead and create the rest of the directories and files we'll need in the root of our project.

  • /assets - A directory for storing assets related to displaying information about our starter. In this case, preview images for the overall project and for each site the starter contains
  • /data - A directory to store a Sanity dataset export
  • README.md - The README file for this project will be displayed on the Create page.
  • sanity-template.json - A JSON file containing details about the Starter as well as deployment information.


Creating metadata and deployment information in sanity-template.json

In the sanity-template.json file we just created, we need to provide an object of information about our Starter.

Add Starter metadata

To start, we'll add a bit of information about the starter. We'll add a title, a description, a preview image, and an array of relevant technologies.

{
  "version": 2,
  "title": "Sanity.io starter template for Netlify",
  "description": "Minimal and barebones example of a starter for deployment on Netlify",
  "previewMedia": {
    "type": "image",
    "src": "assets/netlify.png",
    "alt": "Netlify"
  },
  "technologies": [
    {
      "id": "netlify",
      "name": "Netlify",
      "url": "https://www.netlify.com/"
    }
  ]
}


This information is primarily displayed on sanity.io/create. The version property is important to note. This property is the version of the Create API and should be set to 2.

The overall Starter can have a previewMedia object. This is where we can define out an image to use for the starter. We'll use this same object in the next section when defining our individual sites. This object is not required by the API, but makes for a nicer experience when a developer is looking at the Starter. It also will be important for getting accepted into the featured community Starters list on the Create page.

Add deployment information

Next, we need to provide the Create API with information to pass on to our deployment host. In this case, we'll be using Netlify as our host. We need to provide information about the sites Netlify will be deploying for us, as well as any metadata to show to developers creating the site.

You can publish multiple sites in this way. Each will take a unique id and be configured to either be a studio site or a web site.

{
  // Starter metadata omitted for clarity
  "deployment": {
    "provider": "netlify",
    "sites": [
      {
        "id": "studio",
        "type": "studio",
        "title": "Sanity Studio",
        "description": "The Sanity Studio is where you edit and structure your content.",
        "dir": "./studio",
        "previewMedia": {
          "type": "image",
          "src": "assets/studio.jpg",
          "alt": "A preview image of the Sanity Studio."
        },
        "buildSettings": {
          "base": "studio",
          "dir": "dist",
          "cmd": "npm run build && cp netlify.toml dist"
        },
        "requirements": ["build-hook"]
      },
      {
        "id": "web",
        "type": "web",
        "title": "Blog Website",
        "description": "A minimal example of a frontend fetching data from Sanity.io.",
        "dir": "./web",
        "previewMedia": {
          "type": "image",
          "src": "assets/frontend.png",
          "alt": "A preview image of the webpage."
        },
        "buildSettings": {
          "base": "web",
          "dir": "public",
          "cmd": "cp index.html public/index.html"
        },
        "requirements": ["build-hook"],
      }
    ]
  }
  
}

There's a lot to break down in this snippet. Our deployment is represented by an object. The object contains a deployment provider. In this case, it's netlify.

Next, we define each of our sites in a sites array. Each site is represented by an object that contains metadata (similar to our Starter overview), as well as deployment information for our provider.

Each site has a title, description, and preview image like our Starter. This information is displayed on the Starter's landing page. They also require an id and a type. The id is a unique identifying string. The type corresponds to either web for a frontend or studio for a Studio installation. The studio type has a little extra magic to sync things up with a Sanity project.

The dir property contains a string representation of where this site lives relative to the /template directory. This tells the provider where to find the site in the Git repository.

The buildSettings object provides details for Netlify to use. The base property is the directory in which Netlify will run its deployment. The dir property is the final "public" directory for Netlify to upload to its CDN. The cmd property is the command for Netlify to run to build the current site.

Was this article helpful?