@tinloof/sanity-studio

A collection of studio plugins, fields, and components to boost your Sanity studio.

Installation

npm install @tinloof/sanity-studio

Table of contents

• Table of contents
• Pages
  • Basic usage
  • Enabling page creation
  • Enabling internationalization
• Sections
  • Create a new section schema
  • Create a sections list array
  • Add a section picker to your document
  • Add sections to your Sanity schema
• documentI18n
• localizedItem
• defineIcon

Pages

Pages is a plugin that wraps Presentation to display your website pages in a sitemap-like navigation and make it possible to create new ones.

Basic usage

1. Configure Pages:

import { pages } from "@tinloof/sanity-studio";

export default defineConfig({
  // ... other Sanity Studio config
  plugins: [
    pages({
      // Presentation's configuration
      previewUrl: {
        previewMode: {
          enable: "/api/draft",
        },
      },
    }),
  ],
});

2. Add a pathname field to page schemas using the definePage helper:

import { definePathname } from "@tinloof/sanity-studio";

export default defineType({
  type: "document",
  name: "modularPage",
  fields: [
    definePathname({
      name: "pathname",
    }),
  ],
});

Documents with a defined pathname field value are now recognized as pages and are automatically grouped into directories in the pages navigator.

Like Sanity's native slug type, the pathname supports a source option which can be used to generate the pathname from another field on the document, eg. the title:

import { definePathname } from "@tinloof/sanity-studio";

export default defineType({
  type: "document",
  name: "modularPage",
  fields: [
    definePathname({
      name: "pathname",
      options: {
        source: "title",
      },
    }),
  ],
});

The source can also be a function (which can be asynchronous), returning the generated pathname.

Enabling page creation

Use the creatablePages option to define which schema types can be used to create pages.

When a page is created, it will automatically have the current folder in its pathname.

import { pages } from "@tinloof/sanity-studio";

export default defineConfig({
  // ... other Sanity Studio config
  plugins: [
    pages({
      // Add any documents you want to be creatable from the pages navigator
      creatablePages: ["page"],
      previewUrl: {
        previewMode: {
          enable: "/api/draft",
        },
      },
    }),
  ],
});

Enabling internationalization

The i18n option can be used to support filtering pages by a locale field and display internationalized URLs.

When page creation is enabled, the currently selected locale is also used as an initial value to create new pages.

Pathnames are automatically validated to be unique accros locales.

import { pages } from "@tinloof/sanity-studio";

const i18nConfig = {
  locales: [
    { id: "en", title: "English" },
    { id: "fr", title: "French" },
  ],
  defaultLocaleId: "en",
};

export default defineConfig({
  // ... other Sanity Studio config
  plugins: [
    pages({
      i18n: i18nConfig,
      previewUrl: {
        previewMode: {
          enable: "/api/draft",
        },
      },
    }),
  ],
});

/**
 * Don't forget to add i18n options and locale field to your document schema
 */
export default defineType({
  type: "document",
  name: "page",
  fields: [
    definePathname({
      name: "pathname",
      options: {
        // Add i18n options
        i18n: {
          enabled: true,
          defaultLocaleId: i18nConfig.defaultLocaleId,
        },
      },
    }),
    // Add locale field
    defineField({
      type: "string",
      name: "locale",
      hidden: true,
    }),
  ],
});

Support documents without a locale

By default, when internationalization is enabled, only pages whose locale field matches the currently selected locale will be shown in the list. If you have page types that are not translated but you still want them to show up in the list, you can set the requireLocale option to false in your i18n config:

const i18nConfig = {
  locales: [
    { id: "en", title: "English" },
    { id: "fr", title: "French" },
  ],
  defaultLocaleId: "en",
  requireLocale: false,
};

Now all documents with a pathname field will show up in the list regardless of the filtered locale, even if they don't have a locale field (or their locale is null).

Lock folder renaming

By default, folders can be renamed. Set the folder.canUnlock option to false to disable this.

import { definePathname } from "@tinloof/sanity-studio";

export default defineType({
  type: "document",
  name: "modularPage",
  fields: [
    definePathname({
      name: "pathname",
      options: {
        folder: {
          canUnlock: false,
        },
      },
    }),
  ],
});

Customizing pages previews

Documents can have their preview customized on the pages navigator using the List Previews API:

export default {
  name: "movie",
  type: "document",
  fields: [
    {
      title: "Title",
      name: "title",
      type: "string",
    },
    {
      type: "image",
      name: "image",
      title: "Image",
    },
  ],
  // Preview information
  preview: {
    select: {
      title: "title",
      media: "image",
    },
    prepare({ title, image }) {
      return {
        title,
        media: image,
      };
    },
  },
};

Customizing folders

By default, folders will have a folder icon and use the pathname/prefix capitalized as the title. You can customize this for individual folders using the folders config option on the plugin:

export default defineConfig({
  // ... other Sanity Studio config
  plugins: [
    pages({
      previewUrl: {
        previewMode: {
          enable: "/api/draft",
        },
      },
      folders: {
        "/news": {
          title: "Articles",
          icon: NewspaperIcon,
        },
      },
    }),
  ],
});

Automatically navigate on pathname change

By default, the pathname field comes with a "Preview" button which is used to navigate to the page within the Presentation iframe when the pathname changes. You can optionally disable this manual button and have the Presentation tool automatically navigate to the new pathname as it changes:

import { definePathname } from "@tinloof/sanity-studio";

export default defineType({
  type: "document",
  name: "modularPage",
  fields: [
    definePathname({
      name: "pathname",
      options: {
        autoNavigate: true,
      },
    }),
  ],
});

The Presentation tool will now automatically navigate to the new pathname as the user types, with a 1 second debounce.

Sections

The defineSection field lets you easily define a new section schema. Used in combination with the SectionsArrayInput component, it will render a useful section picker in your Sanity documents.

1. Create a new section schema

// @/sanity/schemas/sections/banner.tsx
export const bannerSection = defineSection({
  name: "block.banner",
  title: "Banner",
  type: "object",
  options: {
    variants: [
      {
        /**
         * Will be used to display a preview image
         * when opening the section picker
         */
        assetUrl: "/images/blocks/hero.png",
      },
    ],
  },
  fields: [
    defineField({
      name: "bannerSection",
      type: "string",
    }),
  ],
});

2. Create a sections list array

// @/sanity/schemas/sections/index.tsx

import { bannerSection } from "@/sanity/schemas/sections/banner";

export const sections = [bannerSection];

3. Add a section picker to your document

Here, the SectionsArrayInput component is used to render a useful section picker in your Sanity documents.

// @/sanity/schemas/sections/index.tsx

import { sections } = "@/sanity/schemas/sections/index";
import { SectionsArrayInput } from "@tinloof/sanity-studio";

export default defineType({
  name: "page",
  type: "document",
  // ... other fields
  fields: [
    defineField({
      name: 'sectionPicker',
      title: 'Section Picker',
      type: 'array',
      of: sections.map((section) => ({
        type: section.name,
      })),
      components: {
        input: SectionsArrayInput,
      },
    }),
  ]
})
export const sections = [bannerSection];

4. Add sections to your Sanity schema

// @/sanity/schemas/index.tsx

import { sections } from "@sanity/schemas/index";
import page from "@/sanity/schemas/page";

const schemas = [page, ...sections];

export default schemas;

documentI18n

The documentI18n plugin is an opinionated thin wrapper around Sanity's Document Internationalization that makes it possible to add internationalization without having to specify schema types. documentI18n enables internationalization on any schema with a locale field.

Check the with-i18n example for instructions on usage.

localizedItem

The localizedItem utility helps create localized document lists in your Sanity Studio's structure. It creates a nested list structure that groups documents by locale, with an "All" option to view all documents regardless of locale.

Basic usage

import { localizedItem } from '@tinloof/sanity-studio';
import { StructureResolver } from 'sanity/structure';

const locales = [
    { id: 'en', title: 'English' },
    { id: 'fr', title: 'French' },
  ];

export const structure: StructureResolver = (S) => {
  return S.list()
    .title('Content')
    .items([
      localizedItem(S, 'blog.post', 'Blog posts', locales),
    ]);

Parameters

• S: The Sanity Structure Builder instance
• name: The document type name (string)
• title: The display title for the list (string)
• locales: An array of locale objects with id and title properties

Example with additional locale properties

You can include additional properties

const locales = [
  { id: "en", title: "English", countryCode: "US", isDefault: true },
  { id: "fr", title: "French", countryCode: "FR" },
];

localizedItem(S, "blog.post", "Blog posts", locales);

The utility will create a nested structure with:

• A top-level item with the provided title
• An "All" option showing all documents of the specified type
• Individual locale options that filter documents by their locale field

defineIcon

Builds upon a string field with an options list to show a preview of the icon select as well as other options.

Basic usage

import { defineIcon } from "@tinloof/sanity-studio";
import { defineType } from "sanity";

export default defineType({
  type: "document",
  name: "page",
  fields: [
    {
      type: "string",
      name: "title",
    },
    defineIcon({
      name: "icon",
      options: {
        list: [
          { title: "Calendar", value: "calendar" },
          { title: "Chat", value: "chat" },
          { title: "Clock", value: "clock" },
        ],
      },
    }),
  ],
});

Parameters

• options.list: Uses the default string option list type of {title: string, value: string}[]

The ultility searches for icons within the folder /icons/select/[icon-value].svg, if you have a Next.js embbedded setup then store them under /public/icons/select/[icon-value].svg.

Examples

Check the /examples folder.

License

MIT © Tinloof

Develop & test

This plugin uses @sanity/plugin-kit with default configuration for build & watch scripts.

See Testing a plugin in Sanity Studio on how to run this plugin with hotreload in the studio.