A short introduction to Sanity.io

What you need to know to get started with Sanity.io, the platform for structured content.

Sanity.io is the platform for structured content. With Sanity.io 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.io you have access to a bunch of APIs, libraries, and tools for working that helps you leverage the benefits of having all your content behind a single source of truth. This article will quickly walk you through some of the central concepts, giving you a head start of what’s good to know.APIs, libraries, and tools for working that helps you leverage the benefits of having all your content behind a single source of truth. This article will quickly walk you through some of the central concepts giving you a head start of what’s good to know.

Sanity Data Store

Querying for content

When you start a new project on Sanity.io, 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 lets you quickly filter down to the documents you want and project exactly the data structured 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 in transactions described in JSON which let you create and delete documents, set and unset keys with values, 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.io also comes with a complete asset pipeline that lets you upload files and images. When you upload images, Sanity.io will analyze them for metadata such as dimensions, color palettes, and extract a low-quality-image-placeholder datastring 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 an open-source CMS that connects to Sanity.io’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 with JavaScript. You can also create your own widgets for the Dashboard, or whole custom Studio tools to augment editoral 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 to 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 the 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.io 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 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.

Projects, datasets, and tokens

A project gives you a unique ID that you can use to connect to your datastore. You store your JSON documents datasets. Documents within a dataset can reference each other, but not between. Assets that you upload to the datastore is 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.