Sanity Integration

This guide will walk you through integrating Fusion with a Sanity CMS.

Starter Templates

Our Next.js and Sanity starter templates includes the Fusion Sanity integration package installed and configured. You can use it as a starting point for your project.


npm init @codedazur/app@latest

Manual Integration

Prerequisites

In addition to the prerequisites for the Getting Started guide, you will need to create a Sanity project and set up a local development environment for it. Please refer to the Sanity documentation for more information.

This guide assumes you’re using Next.js (but any React framework will do) and that your project has the following directory structure:

Installation

To connect Fusion with the Sanity CMS, you will need to install two additional dependencies.

First, add the Fusion Sanity integration package to your React application.


cd apps/next
npm install @codedazur/fusion-sanity

Then, navigate to your Sanity project and install the Sanity plugin.


cd ../sanity
npm install @codedazur/sanity-plugin-fusion

Create a Document Type

Next, you will need to create a document type for your pages that will allow content editors to to add Fusion’s sections. You can define your documents however you like, but below is a simple example.

apps/sanity/schemas/documents/myPage.ts


import { FieldType, SectionData } from "@codedazur/sanity-plugin-fusion";
import { Image, SanityDocument, Slug, defineField, defineType } from "sanity";
 
/**
 * @todo Move this enum to a shared location later.
 */
enum DocumentType {
  MyPage = "myPage",
}
 
export interface MyPageDocument extends SanityDocument {
  _type: DocumentType.MyPage;
  title: string;
  path: Slug;
  image: Image;
  sections: SectionData[];
}
 
/**
 * A minimal page that supports all of the standard Fusion sections for its
 * content.
 */
export const myPage = defineType({
  type: "document",
  name: DocumentType.MyPage,
  title: "My Page",
  preview: {
    select: {
      title: "title",
      media: "image",
    },
  },
  fields: [
    defineField({
      type: "string",
      name: "title",
    }),
    defineField({
      type: "slug",
      name: "path",
      options: {
        source: "title",
      },
    }),
    defineField({
      type: "image",
      name: "image",
      options: {
        hotspot: true,
      },
    }),
    defineField({
      type: FieldType.Sections,
      name: "sections",
    }),
  ],
});

As you can see in this example, you can use the FieldType.Sections field type to add an array field with the default section configuration. If you want more control over the sections that are allowed in your document, you can provide your own array of section types.


defineField({
  type: FieldType.Sections,
  name: "sections",
  options: {
    sections: [
      SectionType.InfoSection,
      SectionType.ImageSection,
    ]
  }
}),

Or, you can mutate the default sections using a callback, for example to filter out some of the sections you don’t want.


defineField({
  type: FieldType.Sections,
  name: "sections",
  options: {
    sections(sections) {
      // Return all sections except for the Info and Image sections.
      return sections.filter((section) => ![
        SectionType.InfoSection,
        SectionType.ImageSection,
      ].includes(section));
    }
  }
}),

Configure the Sanity Plugin

The @codedazur/sanity-plugin-fusion package contains the schema definitions for all of the components that can be configured in the CMS. To install the plugin, add it to your plugins configuration in sanity.config.ts.

sanity.config.ts


import { fusion } from "@codedazur/sanity-plugin-fusion";
import { defineConfig } from "sanity";
import { DocumentType, myPage } from "./schemas/documents/myPage";
// ...
 
export defineConfig({
  // ...
  plugins: [
    // ...
    fusion({
      routes: [DocumentType.MyPage],
    }),
  ],
  schema: {
    types: [myPage],
  },
});

The routes array is used for references on internal links. Add any names or definitions of document schemas that you want buttons and links to be able to navigate to within your website.

In addition, you can optionally provide an array of theme names and an array of aspect ratios.


fusion({
  routes: [DocumentType.MyPage],
  themes: [
    { value: "light", title: "Light" },
    { value: "dark", title: "Dark" },
  ],
  aspectRatios: ["16:9", "4:3"],
}),

The aspect ratios you choose must be supported by Fusion. If you don’t provide this array, all supported aspect ratios will be allowed.

Note

You can also customize which schemas are registered by the plugin using the sections and fields options. For more information, see the Sanity Plugin Configuration reference.

Create a Document

Now, start your local development server, open Sanity in a browsser and create an instance of your document.

Note

If your development server complains about a missing projectId, you still need to go through Sanity’s initialization. For more information on setting up a Sanity project, please refer to Sanity’s documentation.

If you’re following along with this guide, fill in "/" for the slug, because we will query on that slug in the next step. Add any sections you like so that we have something to render in the next step.

Render your Document

In your Next.js application, create a page that queries the Sanity API and renders your page’s sections. For this example, we will work with a hard-coded slug set to "/", but this approach can be extended to work with dynamic routes.

apps/next/app/page.tsx


import { Sections } from "@codedazur/fusion-sanity";
import { notFound } from "next/navigation";
import { groq } from "next-sanity";
import { sanity } from "../sanity";
import {
  DocumentType,
  MyPageDocument,
} from "../../sanity/schemas/documents/myPage";
 
export default async function Page() {
  const document = await sanity.fetch<MyPageDocument | undefined>(
    groq`*[_type="${DocumentType.MyPage}" && slug.current="/"][0]`,
  );
 
  if (!document) {
    return notFound();
  }
 
  return <Sections sanity={sanity.config()} sections={document.sections} />;
}

If you start your Next.js development server and visit your app’s home page, you should see the sections you added to your page in the CMS in the previous step.

Next Steps

With these foundational pieces in place:

Your Sanity Studio is configured with Fusion schemas.
Your frontend application has the necessary providers and basic setup.
You’ve seen a basic example of defining a page with sections in Sanity and rendering it in Next.js.

You are now ready to:

Explore the full range of schemas provided by @codedazur/sanity-plugin-fusion.
Dive deeper into fetching various data structures from Sanity.
Learn how to customize the rendering of specific Sanity types by creating or overriding adapters.
Customize the look and feel of fusion-ui components through its theming system.