Integrate Sanity with Next.js

If you are reading this article from my personal website (danielfullstack.com), then you are actually reading a blog that powered by Sanity CMS, which I am writing about today.

Sanity CMS is a headless content management system that integrates seamlessly with Next.js, and provides countless benefits from only the free tier!

By the end of this article, you will:

Have a working Sanity Project set up and ready to be used.
Be able to fetch your content from inside your Next.js apps.
Gain comprehensive knowledge on how Sanity works, and why it's a great headless CMS.

So without further ado... Let's dive right in!

Install dependencies

npm i @sanity/cli @sanity/image-url @sanity/vision next-sanity sanity styled-components @sanity/types

Create a Sanity Project

Create a sanity account
Create a new sanity project
Select "From scratch with CLI." (You may also select the other option if you are already comfortable with sanity).

Setup Environment Variables

1. Now we need to find your projectId and dataset.

Your projectId should be on your new project page, and also in the URL as follows: https://www.sanity.io/manage/personal/project/PROJECT_ID
Your dataset should be available here: https://www.sanity.io/manage/personal/project/PROJECT_ID/datasets. By default it should be called production

2. Create a file src/sanity/env.ts and save your projectId and dataset:

export const apiVersion = "2024-07-31"
 
export const dataset = "YOUR_DATASET"
 
export const projectId = "YOUR_PROJECT_ID"

Setup Next.js with Sanity

There are quite a few files necessary to make Sanity work with Next.js.

I will list each file path relative to your Next.js directory, with the code and a relevant explanation below:

sanity.config.ts

"use client"

/**
 * This configuration is used to for the Sanity Studio that’s mounted on the `\src\app\studio\[[...tool]]\page.tsx` route
 */
import { visionTool } from "@sanity/vision"
import { defineConfig } from "sanity"
import { structureTool } from "sanity/structure"

// Go to https://www.sanity.io/docs/api-versioning to learn how API versioning works
import { apiVersion, dataset, projectId } from "./src/sanity/env"
import { schema } from "./src/sanity/schema"

export default defineConfig({
  basePath: "/studio",
  projectId,
  dataset,
  // Add and edit the content schema in the './sanity/schema' folder
  schema,
  plugins: [
    structureTool(),
    // Vision is a tool that lets you query your content with GROQ in the studio
    // https://www.sanity.io/docs/the-vision-plugin
    visionTool({ defaultApiVersion: apiVersion }),
  ],
})

This is the most important file. This is the configuration file for your sanity project.

sanity.cli.ts

/**
 * This configuration file lets you run `$ sanity [command]` in this folder
 * Go to https://www.sanity.io/docs/cli to learn more.
 **/
import { dataset, projectId } from "@/sanity/env"
import { defineCliConfig } from "sanity/cli"

export default defineCliConfig({ api: { projectId, dataset } })

This file ensures that your sanity CLI has the correct information to be able to communicate with your project. You can use the CLI by typing npm sanity.

src/app/studio/[[...tool]]

/**
 * This route is responsible for the built-in authoring environment using Sanity Studio.
 * All routes under your studio path is handled by this file using Next.js' catch-all routes:
 * https://nextjs.org/docs/routing/dynamic-routes#catch-all-routes
 *
 * You can learn more about the next-sanity package here:
 * https://github.com/sanity-io/next-sanity
 */

import { NextStudio } from "next-sanity/studio"

import config from "../../../../sanity.config"

export const dynamic = "force-static"

export { metadata, viewport } from "next-sanity/studio"

export default function StudioPage() {
  return <NextStudio config={config} />
}

This is the only Next.js specific file. It is necessary to be able to access sanity studio on your website (e.g. example.com/studio).

src/sanity/schema.tsx

import { type SchemaTypeDefinition } from "sanity"

export const schema: { types: SchemaTypeDefinition[] } = {
  types: [
    {
      name: "blog",
      type: "document",
      title: "Blog",

      fields: [
        {
          name: "title",
          type: "string",
          title: "Title",
          validation: (Rule) => Rule.required(),
        },
        {
          name: "subtitle",
          type: "string",
          title: "Subtitle",
        },
        {
          name: "slug",
          type: "slug",
          title: "Slug",
          options: {
            source: "title",
          },
          validation: (Rule) => Rule.required(),
        },
        {
          name: "image",
          type: "image",
          title: "Image",
          options: {
            hotspot: true,
          },
          fields: [
            {
              name: "caption",
              type: "string",
              title: "Caption",
            },
          ],
          validation: (Rule) => Rule.required(),
        },
        {
          name: "content",
          type: "array",
          title: "Content",

          of: [
            {
              type: "block",
              marks: {
                annotations: [
                  {
                    name: "link",
                    type: "object",
                    title: "Link",
                    fields: [
                      {
                        name: "href",
                        type: "url",
                        title: "URL",
                      },
                    ],
                  },
                ],
              },
            },
            {
              name: "Image",
              type: "image",
              title: "Image",
              options: {
                hotspot: true,
              },
              fields: [
                {
                  name: "caption",
                  type: "string",
                  title: "Caption",
                },
              ],
            },
          ],
        },
      ],
    },
  ],
}

This file holds your sanity schema, which defines the shape of your content.

This is an example boilerplate for a blog schema, but feel free to change this by referencing the docs.

src/sanity/lib/client.ts

import { createClient } from "next-sanity"

import { apiVersion, dataset, projectId } from "../env"

export const client = createClient({
  projectId,
  dataset,
  apiVersion,
  useCdn: true, // Set to false if statically generating pages, using ISR or tag-based revalidation
})

Defines the client API that lets you fetch your content from Sanity using code.

src/sanity/lib/image.ts

import createImageUrlBuilder from "@sanity/image-url"
import { SanityImageSource } from "@sanity/image-url/lib/types/types"

import { dataset, projectId } from "../env"

// https://www.sanity.io/docs/image-url
const builder = createImageUrlBuilder({ projectId, dataset })

export const urlFor = (source: SanityImageSource) => {
  return builder.image(source)
}

This file will take in a sanity image object, then extract the image URL that can be used to render an image inside your Next.js application.

Using Sanity to Fetch Data

To fetch data from Sanity, we need to understand the query language that is used; GROQ.

GROQ syntax took me only a few hours to fully understand, because Sanity have excellent docs to make this process easy.

Now that you understand basic GROQ, lets create a function to fetch our blog posts from sanity.

src/sanity/lib/blogs.ts

import { groq } from "next-sanity"

import { client } from "./client"

export async function getBlogs() {
  // ! https://www.sanity.io/docs/query-cheat-sheet
  const query = groq`*[_type == "blog"]`

  const blogs = await client.fetch(query)

  return blogs
}

As you can see, we utilize the groq function to pass in a GROQ query that returns all our blog posts (using our boilerplate schema.tsx file).

Now lets render out these blogs by defining a React server component:

import { getBlogs } from "@/sanity/lib/blogs"

interface BlogPostsProps {}

// ! Fetches all blog posts using getBlogs from src/sanity/lib/blogs.ts
export const BlogPosts = async ({}: BlogPostsProps) => {
  const posts = await getBlogs()
  console.log(posts)

  return <div>Here you can render your blog posts</div>
}

Now let's see the output when I create a blog using sanity studio.

Using the Sanity CLI

Configuring the Sanity CLI is simple, and you would need to do this if you want to test your sanity studio locally, and if you want to deploy it.

Here is a quick guide on how to configure the sanity CLI available on my website, which mentions the most important commands.

Conclusion

Sanity CMS is amazing, but with so many features, there comes complexity to use it with technologies such as Next.js.

I hope that I reduced this complexity for you, since I used to have trouble configuring sanity, and now I want to make the process smooth for everyone else.

If you want to make the process lightning fast, however, feel free to check out the sanity plugin on my website, which will scaffold all the necessary files for you instantly with a single CLI command:

https://www.nextinject.pro/plugins/backend/sanity

If you enjoyed this article, please make sure to Subscribe, Clap, Comment and Connect with me today! 🌐