Index

Getting started

Sanity treats your content as structured data and makes it easily available over an API. 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.

Seriously: Feel free to ping us on Gitter for a chat should you have questions or get stuck along the way.

  1. Install CLI tooling

    npm install -g @sanity/cli

    Didn't have Node and npm installed? Read this.

    The command line tool sets up new projects, manages datasets, imports data and also has other useful features. We'll be using it to get your project up and running.

  2. Bootstrap a project

    sanity init

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

    The studio is lean – pretty much all logic and code is contained in NPM packages. This makes it really easy to upgrade to new versions, and to install and ship plugins as self-contained packages.

  3. Run the studio

    sanity start

    This builds the javascript required to run the studio, and starts a local web server. As you save your code it rebuilds the studio and refreshes the browser.

    The studio is just an HTML file and some javascript bundles that run in your browser. The studio talks to the Sanity API which stores your data and lets you query it from whatever platform or front-end you want.

  4. Edit the schema

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

    The schema defines your data model. We recommend that you start by modelling your data logically, without thinking too much about how it's going to be presented. We've written about why this often makes a lot of sense.

    Schemas are a pretty big topic. For now, take a quick look at how the schema is defined, and move on to the next step.

  5. Deploy the studio

    sanity deploy

    You can to host as you like, 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 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. It's taken care of when you deploy to our servers, but if you host the project yourself, you need to set up what origins to allow by using the Sanity project dashboard.


  6. Create a front-end

    Now that you've got a fully customizable real-time CMS up and running, you'll probably want to fetch and display some data. We don't want to tell you how to present your data or what 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. But in case you need some inspiration, see below for a few pointers on how to get started using 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.