Plugin Plugin protocol schemas
@module studio/plugin
Studio Plugin Protocol
Defines the specification for Studio plugins — a VS Code-like extension model
that allows each metadata type to contribute custom viewers, designers,
sidebar groups, actions, and commands.
Like VS Code extensions, Studio plugins have two layers:
Manifest (Declarative) — JSON-serializable contribution pointsActivation (Imperative) — Runtime registration of React components & handlers
┌─────────────────────────────────────────────────────────┐ │ Studio Host │ │ ┌───────────────────────────────────────────────────┐ │ │ │ Plugin Registry │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ Object │ │ Flow │ │ Agent │ ... │ │ │ │ │ Plugin │ │ Plugin │ │ Plugin │ │ │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ └───────────────────────────────────────────────────┘ │ │ │ │ ┌─── Sidebar ───┐ ┌──── Main Panel ────────────────┐ │ │ │ [plugin icons] │ │ PluginHost renders viewer │ │ │ │ [plugin groups]│ │ from highest-priority plugin │ │ │ └────────────────┘ └────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘ @example
import { StudioPluginManifestSchema } from '@objectstack/spec/studio' ; const manifest = StudioPluginManifestSchema. parse ({ id: 'objectstack.object-designer' , name: 'Object Designer' , version: '1.0.0' , contributes: { metadataViewers: [{ id: 'object-explorer' , metadataTypes: [ 'object' , 'objects' ], label: 'Object Explorer' , priority: 100 , modes: [ 'preview' , 'design' , 'data' ], }], }, });
Source: packages/spec/src/studio/plugin.zod.ts
import { ActionContributionSchema, ActionContributionLocationSchema, CommandContributionSchema, MetadataIconContributionSchema, MetadataViewerContributionSchema, PanelContributionSchema, PanelLocationSchema, SidebarGroupContributionSchema, StudioPluginContributionsSchema, StudioPluginManifestSchema, ViewModeSchema } from '@objectstack/spec/studio' ; import type { ActionContribution, ActionContributionLocation, CommandContribution, MetadataIconContribution, MetadataViewerContribution, PanelContribution, PanelLocation, SidebarGroupContribution, StudioPluginContributions, StudioPluginManifest, ViewMode } from '@objectstack/spec/studio' ; // Validate data const result = ActionContributionSchema. parse (data); Property Type Required Description id string✅ Unique action identifier label string✅ Action display label icon stringoptional Lucide icon name location Enum<'toolbar' | 'contextMenu' | 'commandPalette'>✅ UI location metadataTypes string[]optional (default: []) Applicable metadata types
toolbarcontextMenucommandPalette
Property Type Required Description id string✅ Unique command identifier label string✅ Command display label shortcut stringoptional Keyboard shortcut icon stringoptional Lucide icon name
Property Type Required Description metadataType string✅ Metadata type label string✅ Display label icon string✅ Lucide icon name
Property Type Required Description id string✅ Unique viewer identifier metadataTypes string[]✅ Metadata types this viewer can handle label string✅ Viewer display label priority numberoptional (default: 0) Viewer priority (higher wins) modes Enum<'preview' | 'design' | 'code' | 'data' | 'history'>[]optional (default: ["preview"]) Supported view modes
Property Type Required Description id string✅ Unique panel identifier label string✅ Panel display label icon stringoptional Lucide icon name location Enum<'bottom' | 'right' | 'modal'>optional (default: "bottom") Panel location
Property Type Required Description key string✅ Unique group key label string✅ Group display label icon stringoptional Lucide icon name metadataTypes string[]✅ Metadata types in this group order numberoptional (default: 100) Sort order (lower = higher)
Property Type Required Description metadataViewers { id: string; metadataTypes: string[]; label: string; priority: number; … }[]optional (default: []) sidebarGroups { key: string; label: string; icon?: string; metadataTypes: string[]; … }[]optional (default: []) actions { id: string; label: string; icon?: string; location: Enum<'toolbar' | 'contextMenu' | 'commandPalette'>; … }[]optional (default: []) metadataIcons { metadataType: string; label: string; icon: string }[]optional (default: []) panels { id: string; label: string; icon?: string; location: Enum<'bottom' | 'right' | 'modal'> }[]optional (default: []) commands { id: string; label: string; shortcut?: string; icon?: string }[]optional (default: [])
Property Type Required Description id string✅ Unique viewer identifier metadataTypes string[]✅ Metadata types this viewer can handle label string✅ Viewer display label priority numberoptional (default: 0) Viewer priority (higher wins) modes Enum<'preview' | 'design' | 'code' | 'data' | 'history'>[]optional (default: ["preview"]) Supported view modes
Property Type Required Description key string✅ Unique group key label string✅ Group display label icon stringoptional Lucide icon name metadataTypes string[]✅ Metadata types in this group order numberoptional (default: 100) Sort order (lower = higher)
Property Type Required Description id string✅ Unique action identifier label string✅ Action display label icon stringoptional Lucide icon name location Enum<'toolbar' | 'contextMenu' | 'commandPalette'>✅ UI location metadataTypes string[]optional (default: []) Applicable metadata types
Property Type Required Description metadataType string✅ Metadata type label string✅ Display label icon string✅ Lucide icon name
Property Type Required Description id string✅ Unique panel identifier label string✅ Panel display label icon stringoptional Lucide icon name location Enum<'bottom' | 'right' | 'modal'>optional (default: "bottom") Panel location
Property Type Required Description id string✅ Unique command identifier label string✅ Command display label shortcut stringoptional Keyboard shortcut icon stringoptional Lucide icon name
Property Type Required Description id string✅ Plugin ID (dot-separated lowercase) name string✅ Plugin display name version stringoptional (default: "0.0.1") Plugin version description stringoptional Plugin description author stringoptional Author contributes { metadataViewers: object[]; sidebarGroups: object[]; actions: object[]; metadataIcons: object[]; … }optional (has default)
previewdesigncodedatahistory
ObjectStack