Go Behind the Experience to see how Tecovas brings the West to life with Sanity 🤠 July 18th
Published May 23, 2023

Create your own Sanity template

By Marius LundgĂĄrd & Martin Jacobsen

Creating a reusable project template for Sanity.io can streamline your development process, ensuring consistency across different projects, and reducing the time required to get a new project off the ground. This guide takes you through the steps to build a customizable and reusable Sanity.io template.

Git repository

Begin by setting up a Git repository for your template. This is necessary to register the template on the Sanity Exchange.

The following git hosting services are supported:

Template naming conventions

Prefix your template name with sanity-template-*.

Anything beyond the prefix is optional. However, it’s customary to follow this formula:

sanity-template-<framework>-<use-case>

For example, if building a portfolio (use case) template for Next.js (framework), the name would be sanity-template-nextjs-portfolio.

Local development

Once you have chosen a framework and a use case for your template, and you have some files in the repository and perhaps a development server that you can start and stop, it’s a good idea to add .env files to ensure a smooth connection to Sanity during development and post-instantiation.

We recommend using these files:

  • .env.local (ignored by git)
  • .env.local.example

The .env.local.example should contain an example environment variable file:

# Required, find them on https://manage.sanity.io
NEXT_PUBLIC_SANITY_PROJECT_ID=
NEXT_PUBLIC_SANITY_DATASET=
# see https://www.sanity.io/docs/api-versioning for how versioning works
NEXT_PUBLIC_SANITY_API_VERSION=

# For previews (gives access to draft content)
SANITY_API_READ_TOKEN=

# For automations, integrations, and customizations
# Use it from serverless functions, CI workflows, CLI scripts, etc
SANITY_API_WRITE_TOKEN=

The .env.local.example is intended to be copied and edited by the user after template instantiation like so:

# Copy the env file
cp .env.local.example .env.local

# Edit the env file
code .env.local

Configuring a Sanity project and dataset


In order to build your template, you probably want to create a new Sanity project with two datasets for the following purposes:

  1. A dummy dataset for development, e.g., named development.
  2. A production dataset that can be cloned by users, e.g., named production.

If you’re using Next.js (see Vercel templates below), these environment variables will be available by default:

const projectId = process.env.NEXT_PUBLIC_SANITY_PROJECT_ID
const dataset = process.env.NEXT_PUBLIC_SANITY_DATASET

However, if you’re using a framework that doesn’t automatically load environment variables from .env.local, you might want to look into using dotenv-flow.

Initial data

While your Sanity Studio and frontends should ideally work with empty Sanity datasets, some templates may benefit from initial data for ease of comprehension and usage. You can import this data using the Sanity CLI:

sanity dataset import ./path/to/initial/dataset.tar.gz production

Setting up Vercel templates (1)

Vercel , popular for deploying and maintaining the Next.js framework, also provides an automation feature through its integration with Sanity, making template creation easier.

Sanity’s Vercel integration

Vercel Integration ID: ac_hb2LITYajhRQ0i4QznmKH7gx

The Sanity-Vercel integration automates:

  • Sanity project and dataset creation
  • Vercel environment variable configuration

In addition to the default automation from Vercel:

  • GitHub repository creation
  • Vercel project and deployment setup

Environment variables

Certain environment variables will be available for every Sanity template instantiation on Vercel:

  • SANITY_API_READ_TOKEN
    A Sanity token for read-only operations. Grants access to drafts and hidden content.
  • SANITY_API_WRITE_TOKEN
    A Sanity token for write & read operations. Provides access and write privileges to any content.

Framework-specific environment variables

Your template will have these environment variables accessible upon instantiation:

  • <envPrefix>_SANITY_PROJECT_ID
    The Sanity project ID of the newly created project.
  • <envPrefix>_SANITY_DATASET
    The Sanity dataset name for the newly created project.
  • <envPrefix>_VERCEL_GIT_PROVIDER
    Value: github or gitlab or bitbucket
  • <envPrefix>_VERCEL_GIT_REPO_OWNER
    The name of the repository owner, once the template is instantiated.
  • <envPrefix>_VERCEL_GIT_REPO_SLUG
    The name (URL slug) of the repository, once instantiated.

Deploy button

You may optionally embed a deployment button in your README. The Community Studio has a helper for generating this link; see below for more.

<!-- Deploy button -->
[![Deploy with Vercel](https://vercel.com/button)][vercel-deploy]

<!-- Variables -->
[vercel-deploy]: https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fmariuslundgard%2Fsanity-template-nextjs&repository-name=sanity-template-nextjs&project-name=sanity-template-nextjs&demo-title=Next.js%20with%20Sanity&demo-description=A%20Sanity-powered%20Next.js%20app%20with%20instant%20previews&demo-url=https%3A%2F%2Fsanity-template-nextjs-delta.vercel.app%2F%2F%3Futm_source%3Dvercel%26utm_medium%3Dreferral&demo-image=https%3A%2F%2Fuser-images.githubusercontent.com%2F406933%2F211022598-9b541676-fa68-4618-8a56-92381e075260.png&integration-ids=oac_hb2LITYajhRQ0i4QznmKH7gx&external-id=nextjs%3Btemplate%3Dsanity-template-nextjs

Templates without deploy target (2)

For templates not set for automatic deployment, GitHub templates can be used. Refer to the GitHub documentation on creating a template repository and understanding repository templates.

Register your template

Go to sanity.io/templates to submit your Sanity template.

A Sanity team member will review your submission before it goes public. Your submission should include:

  • Demo URL (optional)
    A deployed example of your template.
  • Demo image URL
    A screenshot or marketing image for your template.
    • Make the image (near) 1.6:1 ratio.
    • Ideally no less than 1536x960 px.
    • A screenshot is better than nothing.

Vercel deploy link helper

Use the "Vercel deploy" link from the helper view on the template schema editor for a quick jump to the Vercel deploy page for additional testing.

README

Once approved, your template will appear on sanity.io/templates with its unique landing page, complete with metadata and author information, and a rendition of the README from the template repository. For best practice, include a deploy button in your README.

Sanity – build remarkable experiences at scale

Sanity Composable Content Cloud is the headless CMS that gives you (and your team) a content backend to drive websites and applications with modern tooling. It offers a real-time editing environment for content creators that’s easy to configure but designed to be customized with JavaScript and React when needed. With the hosted document store, you query content freely and easily integrate with any framework or data source to distribute and enrich content.

Sanity scales from weekend projects to enterprise needs and is used by companies like Puma, AT&T, Burger King, Tata, and Figma.

Other guides by authors