Anatomy of a block
Project layout, defineBlock options, manifest fields, and runtime props passed to every Orbix block.
An Orbix block has two required parts:
- A manifest describing its ID, version, display metadata, surfaces, ports, and requested capabilities.
- A React component that receives
BlockRenderPropsand renders the block UI.
Project structure
When you scaffold a local project with create-orbix-block or export a ZIP archive from Block Studio, a block project follows this layout:
src/index.tsx— exports thedefineBlock(...)result as its default export (or named export).manifest.json— standalone JSON manifest validated against@orbixdocs/sdk/manifest.schema.jsonin your editor.src/dev.tsxandindex.html— mount the block inside the local mock-host playground (mountBlockDevHarness) when you runnpm run dev.src/__tests__/block.test.tsx— unit tests usingrenderBlockfrom@orbixdocs/sdk/testing.
Inside Block Studio, you can either keep the manifest inline inside defineBlock({ manifest: { ... }, component }) or import manifest.json.
defineBlock
defineBlock normalizes your manifest, checks manifest.sdk compatibility, registers any state migrations, and registers the block definition in blockStudioRegistry.
import {
defineBlock,
useOrbixState,
useBlockOutput,
type BlockRenderProps,
} from '@orbixdocs/sdk';
interface MetricProps {
unit?: string;
}
interface MetricState {
value: number;
}
export default defineBlock<MetricProps, MetricState>({
manifest: {
id: 'acme.metric-tile',
name: 'Metric Tile',
version: '1.0.0',
sdk: '^3.0.0',
category: 'Analytics',
surfaces: ['block', 'sidebar_panel'],
slashShortcut: '/metric-tile',
outputs: {
currentValue: { type: 'number', label: 'Current Value' },
},
capabilities: {
storage: ['local'],
},
},
properties: {
unit: { type: 'string', default: 'ms', label: 'Unit' },
},
schemaVersion: 1,
component(props: BlockRenderProps<MetricProps>) {
const [state, setState] = useOrbixState<MetricState>(props, { value: 42 });
const unit = props.props?.unit ?? 'ms';
useBlockOutput('currentValue', state.value, {
type: 'number',
label: 'Current Value',
});
return (
<div
style={{
padding: 12,
borderRadius: 10,
background: 'var(--orbix-card-bg, #16171b)',
border: '1px solid var(--orbix-surface-border, #2a2b32)',
color: 'var(--orbix-text-primary, #f4f4f5)',
}}
>
<div>
{state.value} {unit}
</div>
<button
type="button"
disabled={props.isReadOnly}
onClick={() => setState((s) => ({ value: s.value + 1 }))}
>
+1
</button>
</div>
);
},
});Accepted component keys
defineBlock resolves the React component from definition.component, definition.render, definition.Renderer, or definition.default (in that order). If none is provided, it throws OrbixSDKError with code BLOCK_VALIDATION_FAILED.
Development manifest checks
In non-production builds, defineBlock runs validateManifest once per block ID and logs a console.warn with the invalid field name, a hint, and a documentation URL if an optional rule fails (for example, a non-SemVer version or a slashShortcut missing its leading /). Only two errors throw synchronously from defineBlock:
- Missing component (
BLOCK_VALIDATION_FAILED) - Incompatible
manifest.sdkSemVer range (SDK_VERSION_MISMATCH)
Key manifest fields
| Field | Required | Description |
|---|---|---|
id | Yes | Unique lowercase kebab-case or reverse-DNS identifier (my-block or com.acme.my-block). Never use com.orbix.* — that prefix is reserved for built-in Orbix blocks and is rejected when publishing or installing. |
name / displayName | Yes (one of) | Human-readable label shown in the / slash menu and Marketplace. |
version | Yes | Block release version in MAJOR.MINOR.PATCH SemVer format (1.0.0). Defaults to '1.0.0' if omitted in inline code. |
sdk | Optional | SemVer range checked against the active host SDK version (^3.0.0). If omitted, registration succeeds; if set to an incompatible range such as ^2.0.0 or ^4.0.0, registration throws SDK_VERSION_MISMATCH. |
surfaces | Optional | Rendering contexts supported by the block: 'block' (inline in a document), 'fullpage', and 'sidebar_panel'. |
slashShortcut | Optional | Slash menu trigger starting with / (for example '/metric-tile'). |
capabilities | Optional | Permissions requested by the block, such as storage: ['local', 'persistent'], document: ['read', 'write'], or network: { domains: ['api.example.com'] }. See Manifest reference for all keys. |
inputs / outputs | Optional | Reactive dataflow ports exposed to other blocks on the same page. |
BlockRenderProps
Every render passes BlockRenderProps<TProps> to your component:
| Prop | Type | Description |
|---|---|---|
block | Block | Underlying document block record (id, type, content, props). |
props | TProps | Resolved block properties (merged with defaults from properties when using renderBlock or the dev harness). |
blockId | string | undefined | Instance ID of this mounted block. Inside hooks or nested child components, call useBlockId() instead of threading blockId manually. |
isReadOnly | boolean | undefined | true when the page or viewer is in read-only mode. Always disable mutating inputs and buttons when isReadOnly is true. |
isActive / isFocused | boolean | Whether this block currently holds editor selection or focus. |
theme | 'dark' | 'light' | undefined | Active color mode. For full theme metadata and tokens, call useOrbixTheme(). |
onChange | (updates) => void | Low-level host callback for updating block data. Prefer useOrbixState, which batches updates per animation frame, deduplicates unchanged values, and enforces read-only rules. |
setProperty | (key, value) => void | Convenience setter for a single property key on props. |
setOutput / setOutputs | function | Imperative port output helpers. Prefer useBlockOutput inside React components. |
Subpath imports
@orbixdocs/sdk splits optional features into subpath entry points so local builds stay small:
| Subpath | Exports |
|---|---|
@orbixdocs/sdk | defineBlock, validateManifest, state hooks, storage, migrations, block graph ports, document/workspace/database hooks, useOrbixFetch, useOrbixEnv, useOrbixTheme, error classes |
@orbixdocs/sdk/ui | Scope wrappers (PersonalScope, TeamScope, BlockScopeBar, VotingCard), EnvSetupCard, Bento primitives (BentoGrid, BentoCard, StatCard, Chart), and Tailwind UI components (Button, Card, Tabs, Dialog, etc.) |
@orbixdocs/sdk/ai | useOrbixAI |
@orbixdocs/sdk/realtime | useCollaborative, realtimeEngine, useOrbixWebSocket |
@orbixdocs/sdk/testing | renderBlock, createMockBlock, createMockPages, createMockRuntimeContext, TestRunner, expect |
@orbixdocs/sdk/dev | mountBlockDevHarness, BlockDevPlayground, PLAYGROUND_THEMES, applyPlaygroundTheme |
UI imports differ between Block Studio and npm
Inside Block Studio's in-browser bundler, @orbixdocs/sdk and its subpaths resolve to the host's core SDK module, which includes scope components (PersonalScope, TeamScope, VotingCard) but not the Tailwind primitive set (Button, Card, StatCard, BentoGrid, Tabs, Switch). Importing those from @orbixdocs/sdk/ui inside Block Studio throws UnknownSdkExportError. In Block Studio, either import workspace UI primitives from @/components/ui/* (for example @/components/ui/button) or style standard HTML elements with --orbix-* CSS variables so the same file works everywhere.