Index

Getting started

Sanity treats your content as structured data and makes it available through a simple and powerful API. Content can be created and edited in our collaborative editor, called the Content Studio, which is a fully customizable, client-side web application. You can run the studio on your laptop, host it with us on Sanity.io, or deploy it on your own web server.

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

  1. Install CLI tooling

    npm install -g @sanity/cli

    Don't have Node and npm installed? No problem, we have instructions.

    The command line tool is used to set up new projects, manage datasets, import data, and much more. 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 generate the files needed to run the editing environment locally - your own Content Studio.

    The studio is very 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 initial JavaScript code required to run the studio, and starts a local web server. As you modify and save the code, the server will automatically rebuild the studio and refresh the browser.

    The studio is just an HTML file and some JavaScript bundles that run in your browser. It 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, you can just 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 host the studio wherever you like, but we've made it easy for you to get started by deploying it to our cloud platform. When 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'll need to set up which origins to allow in 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 what you want to do with your 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 JavaScript client can be installed with npm:

    npm install --save @sanity/client

    Once installed in your project, the basic usage is:

    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 may also want to have 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:

    <?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 may also want to have a look at the full client documentation.

    We will be creating client libraries for other languages in the future. In the meanwhile, it's pretty eary to use the plan HTTP API. 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"
        },
        ...
      ]
    }

    Just remember to URL-encode your queries. There are obviously other endpoints available for you to use as well, you'll find further details in the HTTP API documentation.