Flexible schemas
Type-safe queries

If you have an existing Sanity project, you may prefer to read the TypeGen Docs for details on how to incorporate type-safety.

What's covered in this guide

You'll create a new free Sanity project, and generate TypeScript types for the Sanity Studio schema types and your front-end's GROQ queries.

Create a new project

Get started by clicking here to create a new free Sanity project using the Next.js template. Or use the command below to get started via the command line.

If you don't already have an account with Sanity, you'll be prompted to create one.

Building later? This guide requires a terminal. Email yourself this command + get an extended 60-day trial of Sanity's paid features to start building when you're back at your desk.

npm create sanity@latest -- --template sanity-io/sanity-template-nextjs-clean --coupon=flex-guide

Now inside this directory, start the development server.

npm run dev

You should now have two apps running:

• http://localhost:3000 – Your Next.js app
• http://localhost:3333 – Your Sanity Studio

These apps are separately configured in the following directories:

├─ /nextjs-app
└─ /studio

The Sanity Studio is configured with code, edits you make to the configuration will render immediately in the development environment.

Content in Sanity Studio is written to a schemaless, cloud-hosted Dataset in what we call the Content Lake.

The Next.js app fetches content using Sanity Client with the GROQ query language.

Update Studio schema types

In your browser, open Sanity Studio. Click to the Structure tool in the header and create a new post type document.

In your code editor, open the schema type file for post type documents – post.ts – and add a new field called readingTime.

export default defineType({
  name: 'post',
  title: 'Posts',
  icon: DocumentTextIcon,
  type: 'document',
  fields: [
    // ...all other fields
    // 👇 add this field
    defineField({
      name: 'readingTime',
      type: 'number'
    })
  ]
  // ...all other attributes
})

You should now see this field when editing a post type document.

Update your types

TypeGen requires two steps to complete:

1. A static "extraction" of your Sanity Studio schema configuration into JSON.
2. Creating Types based on that schema and any GROQ queries the process finds in your code into TypeScript.

Extract your schema types

To update your Types, you'll first need to update the static extraction file from your Sanity Studio

Inside the Studio directory, run the following command:

npx sanity schema extract --enforce-required-fields

Inside your Next.js directory, run the following command:

npx sanity typegen generate

You should see a confirmation message like.

✅ Generated TypeScript types for 31 schema types and 7 GROQ queries in 1 files into: ./sanity.types.ts

Now in the Next.js app, open app/components/Posts.tsx and see how the PostType has been extended to include your new readingTime field.

However, PostType is a representation of the Sanity Studio schema, and may not match what your GROQ query requested. It is better to rely on the generated Types for query responses.

Update your GROQ query types

Sanity supports GraphQL, but GROQ is more widely used to query for Sanity content.

Open queries.ts and see how the Next.js app has multiple GROQ queries for Sanity content.

Inside the postFields variable, add the following line to the projection. This will use the value of your new readingTime field, to a return a boolean if it is not greater than 10.

const postFields = /* groq */ `
  // ... all other fields
  "isLongRead": readingTime > 10,
`

Inside your Next.js directory, update the Types for query responses by re-running TypeGen:

npx sanity typegen generate

Now in Posts.tsx, you can update:

• PostProps to use the AllPostsQueryResult type
• Post to extract isLongRead from the props

// ...all other imports
import { AllPostsQueryResult } from "@/sanity.types";

// Update the `post` type to use query result
const Post = ({ post }: { post: AllPostsQueryResult[0] }) => {
  // You can now access `isLongRead`
  const { _id, title, slug, excerpt, date, isLongRead } = post;

Now the attributes available on the post prop match the GROQ query you wrote to fetch them.

Summary

You've now successfully created a new Sanity project, with a locally configured Sanity Studio.

You're able to rapidly update the schema types for content creators as well as query for that content in creative ways using GROQ.

All maintaining type-safety up and down your stack.