sanity-plugin-singleton-tools

> This is compatible with v4 and v3 of Sanity Studio.

What does this plugin do?

This plugin adds convenience functions to reduce the overhead of creating singleton documents in the Sanity Studio.

In short, this does the following:

- Limits a singleton document's actions to Publish, Unpublish, and Discard Changes.
- Removes the ability to create new versions of the singleton document in both the global Create menu and Structure.
- Adds simple methods for customizing the way your singletons are listed in your Studio's Structure.

Why Use This Plugin vs. Native Sanity Approaches?

While Sanity Studio supports singleton documents through the Structure Builder API, this
plugin eliminates the repetitive boilerplate and provides additional safeguards:

$3

`js
// schema/singletonType.js/ts
import { defineType } from 'sanity';

export const mySingleton = defineType({
name: 'mySingleton',
title: 'My Singleton',
type: 'document',
options: {
singleton: true, // Identify this document as a singleton
},
fields: [
{
name: 'title',
title: 'Title',
type: 'string',
},
...
],
});
`

`js
// structure.js/ts
export const structure = (S, context) =>
S.list()
.items([
...singletonDocumentListItems({ S, context }), // Auto-generates all singletons
...filteredDocumentListItems({ S, context }) // Auto-filters singletons from main list
])
`

Benefits:
- ✅ Minimal configuration with singleton: true
- ✅ Automatic action restrictions (no duplicate creation)
- ✅ Global Create menu integration
- ✅ Helper functions eliminate boilerplate
- ✅ Consistent singleton behavior across your studio

Installation

`sh
npm install sanity-plugin-singleton-management
`

Migration from sanity-plugin-singleton-tools

This plugin is a modernized, actively maintained fork of sanity-plugin-singleton-tools with identical API compatibility. Migration is straightforward:

$3

2. Install this package:
`sh
npm install sanity-plugin-singleton-management
`

3. Update your import statements:
`diff
// sanity.config.js
- import { singletonTools } from 'sanity-plugin-singleton-tools'
+ import { singletonTools } from 'sanity-plugin-singleton-management'

// structure.js
- import { singletonDocumentListItem } from 'sanity-plugin-singleton-tools'
+ import { singletonDocumentListItem } from 'sanity-plugin-singleton-management'
`

That's it! No other code changes are required. Your existing schema configurations and structure customizations will work exactly the same.

$3

`js
//sanity.config.js
import { defineConfig } from "sanity";
import { singletonTools } from "sanity-plugin-singleton-management";

export default defineConfig({
//...
plugins: [singletonTools()],
});
`

$3

`js
//mySingleton.js
export const mySingleton = {
name: "mySingleton",
title: "My Singleton",
type: "document",
options: {
singleton: true, // Identify this document as a singleton
},
};
`

$3

`js
// structure.js
import {
singletonDocumentListItem,
singletonDocumentListItems,
filteredDocumentListItems,
} from "sanity-plugin-singleton-management";
import { PlugIcon } from "@sanity/icons";

export const structure = (S, context) =>
S.list()
.title("Sanity Love Content")
.items([
// Create a list item for each singleton document in your schema that links directly to a document view
...singletonDocumentListItems({ S, context }),
// Create a list item for a specific singleton
singletonDocumentListItem({
S,
context,
// Schema type
type: "mySingleton",
// Required for showing multiple singletons of the same schema type
title: "My Singleton",
// Required for showing multiple singletons of the same schema type
id: "mySingleton",
// Specify a custom icon
icon: PlugIcon,
}),
S.divider(),
// Filter singleton documents out of the default S.documentTypeListItems() to prevent them from being rendered as lists or as duplicates
...filteredDocumentListItems({ S, context }),
]);
``

Appendix

Other reading (Sanity docs):

- Singleton documents
- Filtering out singletons in Structure
- Creating a link to a single edit page

Credits

This project is a fork of sanity-plugin-singleton-tools
originally created by RD Pennell.

License

MIT License \
LICENSE