Skip to Content
OrbixDocs
Block SDK · Getting started

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:

  1. A manifest describing its ID, version, display metadata, surfaces, ports, and requested capabilities.
  2. A React component that receives BlockRenderProps and 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:

manifest.json
package.json
vite.config.ts
index.html
index.tsx
dev.tsx
block.test.tsx
  • src/index.tsx — exports the defineBlock(...) result as its default export (or named export).
  • manifest.json — standalone JSON manifest validated against @orbixdocs/sdk/manifest.schema.json in your editor.
  • src/dev.tsx and index.html — mount the block inside the local mock-host playground (mountBlockDevHarness) when you run npm run dev.
  • src/__tests__/block.test.tsx — unit tests using renderBlock from @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.

src/index.tsx
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.sdk SemVer range (SDK_VERSION_MISMATCH)

Key manifest fields

FieldRequiredDescription
idYesUnique 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 / displayNameYes (one of)Human-readable label shown in the / slash menu and Marketplace.
versionYesBlock release version in MAJOR.MINOR.PATCH SemVer format (1.0.0). Defaults to '1.0.0' if omitted in inline code.
sdkOptionalSemVer 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.
surfacesOptionalRendering contexts supported by the block: 'block' (inline in a document), 'fullpage', and 'sidebar_panel'.
slashShortcutOptionalSlash menu trigger starting with / (for example '/metric-tile').
capabilitiesOptionalPermissions 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 / outputsOptionalReactive dataflow ports exposed to other blocks on the same page.

BlockRenderProps

Every render passes BlockRenderProps<TProps> to your component:

PropTypeDescription
blockBlockUnderlying document block record (id, type, content, props).
propsTPropsResolved block properties (merged with defaults from properties when using renderBlock or the dev harness).
blockIdstring | undefinedInstance ID of this mounted block. Inside hooks or nested child components, call useBlockId() instead of threading blockId manually.
isReadOnlyboolean | undefinedtrue when the page or viewer is in read-only mode. Always disable mutating inputs and buttons when isReadOnly is true.
isActive / isFocusedbooleanWhether this block currently holds editor selection or focus.
theme'dark' | 'light' | undefinedActive color mode. For full theme metadata and tokens, call useOrbixTheme().
onChange(updates) => voidLow-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) => voidConvenience setter for a single property key on props.
setOutput / setOutputsfunctionImperative port output helpers. Prefer useBlockOutput inside React components.

Subpath imports

@orbixdocs/sdk splits optional features into subpath entry points so local builds stay small:

SubpathExports
@orbixdocs/sdkdefineBlock, validateManifest, state hooks, storage, migrations, block graph ports, document/workspace/database hooks, useOrbixFetch, useOrbixEnv, useOrbixTheme, error classes
@orbixdocs/sdk/uiScope wrappers (PersonalScope, TeamScope, BlockScopeBar, VotingCard), EnvSetupCard, Bento primitives (BentoGrid, BentoCard, StatCard, Chart), and Tailwind UI components (Button, Card, Tabs, Dialog, etc.)
@orbixdocs/sdk/aiuseOrbixAI
@orbixdocs/sdk/realtimeuseCollaborative, realtimeEngine, useOrbixWebSocket
@orbixdocs/sdk/testingrenderBlock, createMockBlock, createMockPages, createMockRuntimeContext, TestRunner, expect
@orbixdocs/sdk/devmountBlockDevHarness, 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.

On this page