Tips and tricks for building Sanity schema efficiently

We're big believers in standardisation, it's all around you, you've seen:

• Design systems
• Design tokens
• Componentised design
• React patterns

So we thought to ourselves: "Why should Structured Content be any different?". That's why we've written a fully opinionated guide for building your regular style of website.

Now you might be asking: "surely the whole point of Structured Content is to give the developer the freedom to build whatever they like". This is true, but the reason we've written this guide is to make the whole process of learning about Sanity CMS more uniform, and easier to understand.

This guide won't fit everybody, but it should hopefully give you an understanding of how to better structure content. If you're just looking for a Sanity V3 primer, there's a great layman's breakdown here

The anatomy of a good document

We've broken down a good document to help with understanding the why's and how of writing a piece of Sanity schema.

export default {
  // Get used to camelCase for naming things
  name: "exampleDocument",
  title: "Example document",
  type: "document",
  //   The fields array is where you define the fields
  //   of your document type
  fields: [
    //  The reason we always use Title is because
    //  Sanity defaults to this field when creating previews
    {
      name: "title",
      title: "Title",
      type: "string",
    },
    {
      name: "description",
      title: "Description",
      //  A nice thing to do is to create a rough row limit dependent
      //  on the description. E.g 3 rows for a short description.
      //  You can also add validation but we're not covering that here
      rows: 3,
      type: "text",
    },
    {
      name: "image",
      title: "Image",
      type: "image",
      //  You can also add hotspots to images.
      //  Be aware it's a little trickier if you're using Next Image
      hotspot: true,
      fields: [
        // This is to ensure the alt text is filled out
        {
          name: "alt",
          type: "string",
          title: "Alt Text",
        },
      ],
    },
    // We will explain the basics of portable text in the next section
    {
      name: "portableText",
      title: "Portable text",
      type: "portableText",
    },
  ],
  //   This is how we setup the preview for the document type
  //   When it's a document we almost always use the description
  //   field as the subtitle
  //   However, we advise a little different on a page builder
  preview: {
    select: {
      title: "title",
      subtitle: "description",
      media: "image",
    },
    prepare({ title, subtitle, media }) {
      return {
        title: `${title}`,
        subtitle: `${subtitle}`,
        media,
      };
    },
  },
};

Previews

The most important element of the above content is a preview, that's where your client can actually see the content being populated from the Document pane.

See how much better the data looks on a properly prepared page builder, in comparison to one without any preparation:

Unprepared preview

Prepared preview

The difference is night and day (not just because of light and dark mode), and your future clients will appreciate the effort.

Adding an icon

Something you might have noticed on the prepared preview above, is the little icons to the left of the title and description. Can you see how much clearer it makes it - providing a client with not just a descriptive text of what it is, but also an image to represent.

import {FaNewspaper} from 'react-icons/fa'

export const SingleArticle = {
  title: 'Article',
  name: 'article',
  type: 'document',
  // This icon makes all the difference
  icon: FaNewspaper,
  fields: [
  ...
  ]

Page builders

The faster you get used to adding these little icons and nice little previews, the quicker it becomes to scale your structured content. As a nice little bonus, all these icons get pulled through in arrays and other structures to make it even easier to build a page builder and actually know what you're adding to a page.