Happening this week! Hear how Amplitude built a self-serve marketing engine to drive growth 🚀

What is Sanity? A short introduction

What you need to know to get started with Sanity, the Composable Content Cloud

Sanity is a modern headless CMS (Content Management System). Sanity uses structured content to endlessly re-use content across any channel and a composable approach to help businesses connect to any third-party technology, data source, and front end framework.

With Sanity you can manage your text, images, and other media with APIs. You can also use the open-source single page application Sanity Studio to quickly set up an editing environment that you can customize. With Sanity you have access to a bunch of APIs, libraries, and tooling that helps you leverage the benefits of having all your content available as a single source of truth. This article will quickly walk you through some central concepts, giving you a head start.

Before we dive in, there are three important concepts to bear in mind:

  • Sanity has a real-time datastore for structured content, and supporting APIs for assets, user management, and more.
  • Sanity Studio is a user interface for managing content. It's an open-source React Single Page Application that you can customize and host wherever you want.
  • There are also SDKs, libraries, and tools that let you query your content and integrate it with websites, services, and other applications; wherever you need content.

The Content Lake

Querying for content

When you start a new project on Sanity, you’ll get access to the real-time datastore. This is a schemaless backend that lets you store and query JSON documents, and subscribe to real-time changes. It comes with a query API that uses the query language GROQ to let you quickly filter down to the documents you want, and project exactly the data structure you want your content in. GROQ also let you join documents, both by values and by explicit bi-directional references.

Creating and updating documents

The data store also comes with a powerful API for mutation and patches. With an HTTP POST request, you can send transactions described in JSON which let you create and delete documents, set and unset keys with values, and change those values, even in nested structures. It also lets you update text strings using diff-match-patch, and work with arrays. You don’t have to deal with document locking, and you can use revision ids if you want to explicitly prevent race conditions.

The asset pipeline

Sanity also comes with a complete asset pipeline that lets you upload files and images. When you upload images, Sanity will analyze them for metadata such as dimensions and color palettes, and extract a low-quality-image-placeholder data string and save this to an asset document. It's also possible to enable EXIF and GeoLocation metadata, which is turned off by default because of privacy. The asset CDN also accepts query parameters to transform images on demand. You can request custom resolution, formats, cropping, and out-of-the-box optimizations (such as webp).

Utility endpoints

The datastore also has other endpoints that let you quickly export all your documents in one go, query document revision history, set fine-grained custom access control, integrate with custom authentication controls, and set up webhooks.

Sanity Studio

Sanity Studio is the place where you edit and manage your content. Sanity Studio is an open-source CMS that connects to Sanity’s datastore. It’s a single page application written in React and published on npm. All its source code is published on GitHub. You can set up content types and their fields by setting up your schemas in plain JavaScript which Sanity Studio uses to build the editing environment. Once you have done your changes locally, you can build and deploy the Studio on any web host, for example by running sanity deploy in the command-line tool which will deploy the Sanity Studio to our servers.

Editorial workflows

If you want to change the way documents are structured and listed out for custom editorial workflows, you can do so using Structure Builder. With templates for initial values, you can give editors a head start by letting them create new documents of a type with prefilled values. You can define field validation with out-of-the-box methods, or write completely custom methods with JavaScript. You can also create your own widgets for the Dashboard, or whole custom Studio tools to augment editorial workflows, make shortcuts, and so on.

Advanced customization

Sanity Studio was designed for customization. It is what you want to use instead of building your own CMS. It comes with a bunch of extension points and a plugin ecosystem.

You don’t need to know React to set up Sanity Studio, but if you do, you can customize it further by creating your own custom input components and custom previews. There’s very little need for state management since you’ll be dealing with real-time content that propagates into the components via the props.

Accounts and projects

Users and organizations

You can create a new account on Sanity using your Google or GitHub credentials, or by making a new account with an email and password. An account can have access to any number of projects that you’re added to or have created yourself. You can either invite new, or add existing user accounts to get access to your projects. Users can be given different roles and access rights. You can also create organizations with billing information and connect your projects to those.

Gotcha

Looking to add a project to an organization? Projects are always assigned to an individual upon creation and can then be moved to an organization via the Manage interface.

Projects, datasets, and tokens

A project gives you a unique ID that you can use to connect to your datastore. Your JSON documents are stored in datasets. Documents within a dataset can reference each other, but not between. Assets that you upload to the datastore are also tied to a dataset. You can export and import datasets, and add more to your plan if you need to. You can toggle visibility for datasets to be private or public, or you can set up custom access permissions for more fine-grained visibility. Tokens are randomly generated strings that you can use to give your applications and services different types of access to your projects.

Was this article helpful?