Starter templates

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.

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.

• Create a Vercel Starter
• Create a Netlify Starter

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 of 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.

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. The root of your project should be the final code for deployment. This will contain your studio code and any frontend for your project (e.g., Next.js, 11ty, Gatsby, etc.).

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.

Inside the project root, the repository should have a directory named .sanity-template. This will contain all the metadata required to build and display your starter.

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 manifest.json file​

{
    "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"
          }          
        }
      ]
    }
  }

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 manifest.json file: the overall starter preview and each sites' preview.

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.

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.

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​

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]

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]

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.

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.