Skip to content
👋 Next.js Conf 2024: Come build, party, run, and connect with us! See all events

Sanity Template manifest

The manifest.json file is how to configure a new 1-click Sanity Starter.

The manifest.json file is the key component of creating a 1-click starter for use on sanity.io/create. The file lives in the .sanity-template directory at the root of a new starter and has all the configuration information to create a new starter.

Example sanity-template.json

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

General data about the starter

General information about the starter lives in the root level of the JSON object: title, description, API version, and preview image.

Example

{
    "version": 2, 
    "title": "A Descriptive Title for your Starter",
    "description": "A short description for your starter (maybe a couple sentences)",
    "previewMedia": {
      // ...
    },
    "deployment": {
      // ...
    }
    // ...
}

Properties

  • REQUIREDversionnumber

    The version property contains information about what version of the sanity-template API to use. All new Starters should use 2.

  • REQUIREDtitlestring

    A string that will show on sanity.io/create, GitHub, and Netlify as the title of the project and/or Studio

  • descriptionstring

    A description of what the Starter contains. Best practice would be to have this describe the project in 2-3 sentences. This should contain the primary use case for the Starter, as well as any special information a developer would need to know.

  • previewMediaobject

    An object containing information about the preview image for the entire starter. This appears on the main sanity.io/create page that is generated from the GitHub repository and is the main image before a developer creates the project.

  • REQUIREDdeploymentobject

    An object containing the information required to deploy the site(s) on a given provider.

previewMedia

Preview images are used in 2 locations on the Create page: overview preview and site-specific previews. The assets are stored in the root of the Starter repository in a folder usually named assets.

Example

"previewMedia": {
  "type": "image",
  "src": "assets/path-to-preview-image.png",
  "alt": "Alt text here"
}

Properties

  • REQUIREDtypestring

    A string containing the type of media. At this time, only image is supported.

  • REQUIREDsrcstring

    A string corresponding to where the media lives in the project. By convention, this should be in a root directory called assets.

  • REQUIREDaltstring

    A string of alt text for the resulting image. This should be descriptive of what is contained in the image for accessibility.

deployment

The deployment object contains all the information necessary for a hosting provider to build and deploy the site(s) contained inside a Starter. Depending on the deployment provider, different properties are necessary.

Example

"deployment": {
  "provider": "netlify",
  "sites": [ ... ]
}

Properties

  • REQUIREDproviderstring

    A string corresponding to a supported provider. Currently accepted string values: netlify

  • sites (Netlify only)array

    An array of objects containing the deployment information about specific sites the deployment host will build.

  • corsOrigins (Vercel only)array

    An array of objects containing the origin URL and an allowCredentials boolean. These values will be added to the Sanity project's data. Live URLs will be provided by the application, this should be set to default development URLs for a front-end framework.

  • tokens (Vercel only)Array

    An array of token objects containing a label, role, and envVar. These tokens will be added to your Sanity project and the environment variable will be added to your deployment provider.

  • envVars (Vercel only)Object

    An object containing the projectId and dataset keys. These properties contain an array of strings to name the Sanity Project ID and Dataset information for the deployment platform.

sites object (for Netlify deploys)

Inside the deployment object is an array of sites to be deployed to Netlify. This can be a single object or multiple sites to deploy. These objects contain the information specific to deploying that site. These sites behave as a monorepo inside of Netlify's architecture.

Example

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

Properties

  • REQUIREDidstring

    Unique identifier per site to deploy in the current project.

  • REQUIREDtypestring

    A string corresponding to one of two values: web or studio. The studio value will set up a Studio instance. The web value is for any other project type.

  • REQUIREDtitlestring

    A string corresponding to the site's title. This is displayed both on sanity.io/create as well as in the deployment provider.

  • REQUIREDdescriptionstring

    A string corresponding to the site's description. This is displayed on sanity.io/create.

  • REQUIREDdirstring

    A string corresponding to the path to the site's files.

  • buildSettingsobject

    An object with information for the deployment host to run.

  • previewMediaobject

    An object containing information about the preview image for the specific site launched by the starter. This appears on the main sanity.io/create page that is generated from the GitHub repository after a developer has clicked "Create Project"

  • requiredCorsOriginsArray

    An array of objects containing the origin and allowCredentials properties to set in a Sanity project.

  • requiredTokensArray

    An array of objects that contain the role property and label property. role should contain a string matching a Token role: read, write, and deploy-studio. label should be a human-readable title for the Token.

  • requirementsArray

    An array containing the build-hook string. This will inform Netlify and Sanity to set up a webhook for communication between the platforms.

buildSettings (for Netlify Deploys)

The buildSettings object contains information for a deployment provider to use when building a given site.

Properties

  • basestring

    A string corresponding to the location of the site's files in the generated repository

  • dirstring

    A string corresponding to the location of the built site.

  • cmdstring

    A string corresponding with the command-line command to be run by the deployment host.

Updated on February 13, 2024

Was this article helpful?