Index

Getting started

Sanity is a headless content management system. The collaborative editor, called the Content Studio, is a fully customizable, client-side web application. You can run it on your own laptop, host in on your web server or with us on Sanity.io.

Stuck or have questions? Ping us on Gitter for a chat!

  1. Install CLI tool

    npm install -g @sanity/cli

    The Sanity command line tool helps you set up new projects, manage datasets, import data and other useful features. We'll be using it to get your project up and running.

  2. Bootstrap a new project

    sanity init

    This will log you in to Sanity, create a project, set up a dataset and bootstrap the files needed to run a the editing environment locally. Your own Sanity studio.

    A Sanity studio is very slim once bootstrapped - pretty much all the logic and code is contained in npm packages. This makes it really easy to upgrade to new versions of Sanity, and also to install and ship plugins in self-contained packages.

  3. Run the studio

    sanity start

    The studio now builds the javascript required to run the studio, and starts a local webserver that serves it. It's important to note that this development server just helps you by quickly rebuilding the studio when you are developing on it.

    Really, the studio is just an HTML file and some javascript bundles that run entirely in your browser. The studio communicates with our Sanity API - that stores your data and lets you query for it from whichever platform or frontend you want.

  4. Edit the schema

    <editor-of-your-choice> schemas/index.js

    The schema is what defines your data model. We usually recommend that people start modelling their data into logical pieces, without worrying about how it's actually going to be presented. We've written about this in length, but to summarize; you want your data to be data, not tied to presentation.

    Structuring your data this way will allow you to reuse your data for any purpose, and present it in a way that makes sense for that specific use case. This way you can assemble a general data model into different pages. It also allows you to change your mind about how your data is presented to users.

    Writing a schema is obviously very important, and a pretty big topic. You will find a whole chapter on writing a schema in the documentation. For now, take a quick look at how the schema is defined, and we'll move on to the next step.

  5. Deploy the studio

    sanity deploy

    You're free to host your studio anywhere you want, but we've made it simple for you to get started. By running sanity deploy, the CLI will build your studio to a static bundle of HTML and Javascript and deploy it on a pretty <your-project>.sanity.studio URL.

    Our API requires that you define what origins should be allowed to query the API. This is taken care of for you when you deploy to our servers, but if you want to host the project yourself, you can set up the origins to allow in by using the Sanity project dashboard.

  6. Create a frontend

    Now that you've got a fully customizable CMS up and running, you'll probably be eager to start actually fetching and displaying the data. We don't want to tell you how to display your data or which frameworks to use - the beauty of a headless CMS is that it's totally up to you how you want to use and present the data. We do, however, have a few pointers on how to get started by fetching some data from the API.

    Select a language/environment

    The JS client can be installed from NPM:

    npm install --save @sanity/client

    Once installed in your project, the basic usage is this:

    const sanityClient = require('@sanity/client')
    const client = sanityClient({
      projectId: '<your-project-id>',
      dataset: '<your-dataset>'
    })
    
    client
      .fetch(
        '*[_type == $type][0...5]', // Query
        {type: 'movie'} // Params (optional)
      )
      .then(res => {
        console.log('5 movies: ', res)
      })
      .catch(err => {
        console.error('Oh no, error occured: ', err)
      })

    From there, it's up to you which frameworks and tools you want to use. You might also want to take a look at the full client documentation.

    The PHP client can be installed via composer:

    composer require sanity/sanity-php

    Once installed in your project, the basic usage is this:

    <?php
    use Sanity\Client as SanityClient;
    
    $client = new SanityClient([
      'projectId' => '<your-project-id>',
      'dataset' => '<your-dataset>',
    ]);
    
    $results = $client->fetch(
      '*[_type == $type][0...3]', // Query
      ['type' => 'movie'] // Params (optional)
    );

    From there, it's up to you which frameworks and tools you want to use. You might also want to take a look at the full client documentation.

    We will be creating clients for other languages in the future. In the meantime, you can use the HTTP API pretty easily. For instance, querying for 5 documents:

    $ curl -i 'https://<your-project-id>.api.sanity.io/v1/data/query/<your-dataset>?query=*\[0...5\]'
    
    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    
    {
      "ms": 8,
      "query": "*[0...5]",
      "result": [
        {
          "_id": "11db9f8a-1bfc-4613-a161-6edc8e046802",
          "_type": "movie",
          "title": "Aliens"
        },
        ...
      ]
    }

    Queries should be URL-encoded, and there are obviously more endpoints available for you to use. You'll find more details in the HTTP API documentation.