Setup

After installing the package, follow these three simple steps to integrate Sanity Structure Tool into your studio.

1. Configuration

First, create a file to configure the plugin. This generates the typed utilities and helpers you'll use throughout your project.

src/structure/index.ts

import { structureToolPlugin } from 'sanity-plugin-structure-tool';

export const { structure, defineListItems, helpers } = structureToolPlugin({
  title: 'My Project',
});

Advanced Configuration

For dynamic titles, custom roles, or workspace support, see the full Configuration Guide.

2. Define List Items

Next, define your studio's desk hierarchy in a separate file. You can use either the helpers or raw objects with defineListItems.

JSON

// src/structure/listItems.ts
import { defineListItems } from './index';

const listItems = defineListItems([
  {
    schemaType: 'author',
  },
  {
    title: 'Settings',
    schemaType: 'settings',
    singleton: true,
  },
]);

export default listItems;

Helpers

// src/structure/listItems.ts
import { defineListItems } from './index';

const listItems = defineListItems([
  helpers.listing('author'),
  helpers.singleton('settings', {
    title: 'Settings',
  }),
];

export default listItems;

Advanced Usage

Learn more about type safety and modular items in the Define List Items Guide.

3. Register the Plugin

Finally, add the structure plugin and the SingletonAction to your sanity.config.ts.

sanity.config.ts

import { defineConfig } from 'sanity';
import { SingletonAction } from 'sanity-plugin-structure-tool';
import { structure } from './src/structure';
import listItems from './src/structure/listItems';

export default defineConfig({
  // ... your studio configuration
  plugins: [
    structure({
      listItems,
    }),
  ],
  document: {
    // Required to handle document actions for singletons
    actions: SingletonAction,
  },
});

What is SingletonAction?

The SingletonAction is essential for singletons to work correctly. It ensures that document actions like "Delete" or "Duplicate" are hidden for singletons, while preserving them for regular documents. Learn more in the Singleton Action Guide.

Verification

To confirm everything is working as expected:

1. Start your studio:

npm

npm run dev

yarn

yarn dev

pnpm

pnpm dev

bun

bun dev

2. Navigate to the Structure tab in your browser.
3. You should see your list items (e.g., "Authors" and "Settings") rendered correctly.

Next Steps

Now that your base setup is complete, explore more:

• List Items: Learn how to add icons, filters, and custom parameters.
• Helpers: Learn about the built-in functions to define your structure.
• Examples: See specific examples for each field.
• FAQ: Find answers to common questions.