Vyuh Structure Plugin
The Vyuh structure plugin (@vyuh/sanity-plugin-structure
) is a powerful tool
that helps you organize and combine Sanity schemas from multiple features into a
unified master schema. This guide explains how to use the plugin effectively and
how it integrates with the @vyuh/schema-core
package.
Overview
When building a Vyuh application, each feature defines its schemas and exports
them using the FeatureDescriptor
class from @vyuh/sanity-schema-core
. This
approach ensures:
- Consistent schema organization across features
- Type-safe schema definitions
- Automatic schema registration and combination
- Automatic categorization of schemas by feature in the Desk Structure
The Vyuh structure plugin reads the
FeatureDescriptor
instances and assembles them into a single schema that can be used in your Sanity Studio. Here is how your studio would look after integrating a bunch of features. Notice the automatic grouping of schemas by feature.
Installation
First, install the plugin package in your Sanity Studio project:
cd my-sanity-studiopnpm add @vyuh/sanity-plugin-structure
Install the core schema package in your features. We are assuming that each of
your feature is organized as a separate package with its own package.json
.
cd features/my-featurepnpm add @vyuh/sanity-schema-core
These packages provide:
@vyuh/sanity-schema-core
: Core utilities for defining and organizing Sanity schemas, including theFeatureDescriptor
class@vyuh/sanity-plugin-structure
: The Vyuh structure plugin that combines and organizes your feature schemas
Consider using pnpm workspaces to better organize your Sanity Studio and feature packages. Workspaces allow you to manage multiple packages in a single repository, sharing dependencies and enabling easier development:
# pnpm-workspace.yamlpackages: - 'studio' - 'features/*'
This setup allows you to:
- Keep all feature packages and studio in one repository
- Share dependencies across packages
- Use consistent versioning
- Run commands across all packages
Learn more about pnpm workspaces 🔗.
Using FeatureDescriptor
Basic Structure
Each feature exports its schemas using a FeatureDescriptor
instance. Here is
an example from the conference feature:
import { BuiltContentSchemaBuilder, FeatureDescriptor,} from '@vyuh/sanity-schema-core'import { DocumentDescriptor } from '@vyuh/sanity-schema-system'import { conference } from './documents/conference'import { session } from './documents/session'import { speaker } from './documents/speaker'
// Export all schema typesexport const schemaTypes = [conference, session, speaker]
// Export feature descriptorexport const conference = new FeatureDescriptor({ name: 'conf', title: 'Conference Feature', description: 'Conference management feature', contentSchemaBuilders: [ new BuiltContentSchemaBuilder(conference), new BuiltContentSchemaBuilder(session), new BuiltContentSchemaBuilder(speaker), ],})
Feature Descriptor Properties
The FeatureDescriptor
accepts these key properties:
name
: Unique identifier for the featuretitle
: Display name for the featuredescription
: Optional descriptioncontents
: Array of content descriptors that extend content items with additional capabilities (layouts, validations, etc.)contentSchemaBuilders
: Array of schema builders that define the actual schema types and their structure. Each builder corresponds to a single content type and assembles the correspondingContentDescriptor
elements into a single schema for the content-type.
FeatureDescriptor
also supports the following advanced properties. If you are
also building a Vyuh App, these can be leveraged on the Flutter side.
contentModifiers
: Schema type definitions that modify content schemascontentSchemaModifiers
: Functions that can modify content schemasactions
: Schema definitions for feature-specific actionsconditions
: Schema definitions for feature-specific conditionsanalyticsContexts
: Schema definitions for analytics contexts
These properties are used for advanced customization of your feature’s behavior and capabilities.
Customizing Content Descriptors
For example, to add custom layouts to a content type:
import { ContentDescriptor } from '@vyuh/sanity-schema-core'import { conferenceLayout } from './layouts/conference'
// Create a custom content descriptor for conferenceclass ConferenceDescriptor extends ContentDescriptor { constructor(props: Partial<ConferenceDescriptor>) { super('conf.conference', props) }}
export const conference = new FeatureDescriptor({ name: 'conf', title: 'Conference Feature', contents: [ new ConferenceDescriptor({ layouts: [conferenceLayout], }), ], contentSchemaBuilders: [ new BuiltContentSchemaBuilder(conference), // ... other schema builders ],})
Schema Registration
In your Sanity configuration, register your features using the vyuh
plugin
from @vyuh/sanity-plugin-structure
:
Note: The
vision
andmedia
plugins are also included with the vyuh plugin.
import { defineConfig } from 'sanity'import { vyuh } from '@vyuh/sanity-plugin-structure'import { conference } from './features/conference'import { blog } from './features/blog'
export default defineConfig([ { name: 'default', title: 'My Vyuh Studio', basePath: '/', projectId: 'your-project-id', dataset: 'production',
plugins: [ vyuh({ features: [conference, blog], }), ], },])
Best Practices
- Feature Namespacing: Prefix schema types with feature name (e.g.,
conf.session
) - Type Safety: Use TypeScript for schema definitions using the core types
from Sanity such as
defineType
,defineField
, etc. - Modular Organization: Keep related schemas together in feature packages
- Documentation: Include descriptions for fields and types