Sanity.io raises $9.3m Series A to redefine content management

Starter templates

Central concepts and examples for creating a 1-click Sanity Starter

When creating new Sanity-powered projects, you can create a starter repository to enable 1-click installation and configuration via sanity.io/create. These starter projects allow you to scaffold a project quickly with schema, default data, specific frontends and more.

Creating starter templates

A starter template is a repository hosted on GitHub that contains some meta-information about the starter, example content, and the project files that end up in the repository that is initiated through sanity.io/create.

Repository naming

In order for a starter to be validated and used through sanity.io/create, it needs to follow the following naming convention: it must start with sanity-template-. As a best practice, we recommend the following naming scheme for the rest or the repository name: sanity-template-[main-technology]-[what-it-does]. For example a blog built with Next.js would have a repository name of sanity-template-nextjs-blog.

Project structure

A starter template has a specific structure. The structure allows for certain files to be automatically shipped to end-users and some used for providing more information about the starter.

Project Root

The root of the project is where the metadata about the starter is stored. Only files listed in /templates will be placed in the repository delivered to someone using the starter.

sanity-template.json (required)

This file contains all the information the starter engine needs to create the project. In this file, you define everything from a title and description to the exact rules a deployment vendor will use to deploy the project. Some of this data is used by your deploy target (e.g. Netlify) and some are shown on the Create page.

Read the full documentation on the sanity-template.json file

Gotcha

The version referenced in the JSON object is associated with the version of the sanity-template manifest. There's an older version that uses "version": 1. All new Starters should use "version": 2.

{
    "version": 2, 
    "title": "A Descriptive Title for your Starter",
    "description": "A short description for your starter (maybe a couple sentences)",
    "previewMedia": {
      "type": "image",
      "src": "assets/path-to-preview-image.png",
      "alt": "Alt text here"
    },
    
    "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-path",
          "previewMedia": {
            "type": "image",
            "src": "assets/path-to-image.png",
            "alt": "Alt text here"
          },
          "buildSettings": {
            "base": "studio-path",
            "dir": "dist",
            "cmd": "npm run build"
          }
        },
        {
          "id": "site",
          "type": "web",
          "title": "Title for the project",
          "description": "Description for the project",
          "dir": "./site-directory",
          "buildSettings": {
            "base": "site-directory",
            "dir": "./directory-to-deploy",
            "cmd": "npm run build"
          },
          "previewMedia": {
            "type": "image",
            "src": "assets/path-to-image.png",
            "alt": "Alt text here"
          }          
        }
      ]
    }
  }

/README.md

The content of the README.md in the project’s root folder will be rendered on the landing page on sanity.io/create. This is where you can add some information about the starter’s features and what it can be used for.

/template (required)

In the template folder, you put the files that you want the starter to deploy. This can either be a single application, frontend, or studio, or it can be a monorepo with multiple applications. Each of the deployable sites should have an entry in the sites array in your sanity-template.json.

Gotcha

Some vendors have restrictions on how many projects you can connect to a single GitHub repository. You should check out what those restrictions are if you considering having more than two projects launched from /create.

This directory is the best place to add a public README file for any instructions a developer would need to get up and running with the template. This is also where you'll add any global scripts or NPM packages.

/assets (optional)

This is the folder you typically place any images that you want to use for where the starter is previewed. Typically this could be a screenshot or a logo in the 1.75:1 aspect ratio (or around 850px by 487px). Remember that the image will be shown in a tiny format in some context.

There are 2 preview types dictated by the sanity-template.json file: the overall starter preview and each sites' preview.

/data (optional)

If you want the starter to launch with some example content, you can add an export file from a dataset to a data folder. You may want to consider having all the documents published before you do the export so that the content is the same in the studio as in the frontend and application you deploy with it.

Protip

While this is optional, it can be a stumbling block for developers starting with your template. Any required data for a frontend to work should have test data imported.

Developing a template locally

How you set up the local development of the starter template is up to you. At Sanity.io, we have used Lerna to be able to run multiple projects concurrently, but you might use something else or detail in the documentation on how to start the different parts of the project.

Using the sanity-template tooling

With the sanity-template tooling, you can set up development environments and build flows for starter templates and run validation to check if your starter template will deploy on sanity.io/create. You can use it both as a Node.js package and as a CLI tool.

The sanity-template command has the following commands:

  • build - Used to build the projects as specified in the sanity-template.json directory
  • check - Checks to make sure the sanity-template.json file is valid
  • migrate - Migrates from v1 of starter template manifest to v2
  • lockfiles - Generates lock files for projects to speed up deployment
  • watch - Watches template files and rebuilds

Go to sanity-template’s docs to learn more

Deploying from GitHub

You can deploy a starter from any public GitHub repository as long as it validates to the starter specification:

https://www.sanity.io/create?template=[githubhandle]/sanity-template-[starter-name]

Deploying from commit hashes and branches

If you want to deploy a specific branch or commit, you can use the ref parameter on the URL to pass a commit hash. This is perfect if you want to test how a new feature may deploy.

https://www.sanity.io/create?template=[githubhandle]/sanity-template-[starter-name]&ref=[commit-hash]

Setting up automatic dependency upgrades with Renovatebot

If you want the Studio to keep up with the regular updates Sanity ships, you can set up Renovatebot to automatically make and merge pull requests that bump the Sanity dependencies in the Studio’s package.json.

To configure Renovatebot, add a renovate.json to the stater template folder’s root, with the following configuration:

{
  "extends": [
    "github>sanity-io/renovate-presets:sanity-template"
  ]
}

This configuration extends the base Sanity Studio Renovatebot pattern that will keep Studio and Sanity plugins up to date.

You can extend this configuration to update your other apps, as well. Check out Renovatebot’s documentation to learn more.

Getting a starter featured on sanity.io/create

We want to promote starters that seem well done, useful, interesting, or fun! If you want your starter to be featured on sanity.io/create, post and tell us about in the #i-made-this channel in the community.

Was this article helpful?