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
- 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
- General knowledge of Sanity
- Knowledge of NPM scripts
- Working knowledge of the shell and CLIs
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.
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 exportREADME.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.
In the sanity-template.json
file we just created, we need to provide an object of information about our Starter.
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.
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.