Skip to Content
OrbixDocs
Block SDK · Getting started

SDK Overview

Build interactive React and HTML blocks that run inside Orbix documents, split-view sidebars, and full-page views.

An Orbix block is an isolated component paired with a JSON manifest that users can insert into any page with the / slash menu, dock beside a document in split view, or open as a full-page workspace view.

What you can build

Blocks use @orbixdocs/sdk primitives to persist state, react to surrounding content, and connect to external services:

Two ways to build

You can author blocks directly inside Orbix or develop against the @orbixdocs/sdk TypeScript package locally:

WorkflowWhen to use itHow it runs
Block Studio (app.orbix.so)Create, preview, and publish React or HTML blocks to your workspace, team, or the Marketplace.Compiles TypeScript/JSX with VirtualBundler in the workspace (or runs HTML and polyglot blocks on orbixblocks.com) and publishes directly to Orbix.
Local SDK package (@orbixdocs/sdk)Write unit tests with Vitest, type-check against strict .d.ts definitions, or iterate in a standalone browser harness.Runs in a local mock-host playground (mountBlockDevHarness) and headless test runner (renderBlock).

Publishing always goes through Block Studio

There is no CLI publish command. Even if you write and test a block locally with @orbixdocs/sdk, you bring the source into Block Studio to publish it privately, to a team, or to the Marketplace.

Package subpaths

@orbixdocs/sdk splits optional subsystems into dedicated entrypoints so inline blocks only load what they import:

Import pathExports
@orbixdocs/sdkdefineBlock, state, storage, document, workspace, database, ports, surfaces, permissions, network, secrets, canvas, workers, clipboard, file upload
@orbixdocs/sdk/uiScope wrappers, Bento dashboard cards (BentoGrid, BentoCard, StatCard, Chart), EnvSetupCard, and Tailwind UI primitives (Button, Card, Badge, Input, Tabs, Dialog, Table)
@orbixdocs/sdk/aiuseOrbixAI streaming and structured generation hook
@orbixdocs/sdk/realtimeuseCollaborative, realtimeEngine (broadcast, connectPeer, sse), useOrbixWebSocket
@orbixdocs/sdk/testingrenderBlock, createMockBlockHost, property resolution helpers for Vitest / Testing Library
@orbixdocs/sdk/devmountBlockDevHarness standalone local browser playground

Minimal example

Every React SDK block calls defineBlock with a manifest and a component:

src/index.tsx
import { defineBlock, useOrbixState, type BlockRenderProps } from '@orbixdocs/sdk';

interface CounterState {
  count: number;
}

export default defineBlock({
  manifest: {
    id: 'acme.counter',
    name: 'Counter',
    version: '1.0.0',
    sdk: '^3.0.0',
  },
  component(props: BlockRenderProps) {
    const [state, setState] = useOrbixState<CounterState>(props, { count: 0 });

    return (
      <div
        style={{
          padding: 16,
          borderRadius: 12,
          background: 'var(--orbix-card-bg, #16171b)',
          border: '1px solid var(--orbix-surface-border, #2a2b32)',
          color: 'var(--orbix-text-primary, #f4f4f5)',
          display: 'flex',
          alignItems: 'center',
          gap: 12,
        }}
      >
        <span>Count: {state.count}</span>
        <button
          type="button"
          disabled={props.isReadOnly}
          onClick={() => setState((prev) => ({ count: prev.count + 1 }))}
        >
          Increment
        </button>
      </div>
    );
  },
});

Next steps

  • Knowledge Graph View example — see a complete block that maps workspace pages, headings, and links on an interactive canvas.
  • Spaced-Repetition Flashcards example — turn toggle blocks in a document into an interactive flip-card study deck with per-viewer review state.
  • Multiplayer Team Poll example — build a live team poll where each member votes in their own slot without overwriting teammates, paired with private personal notes.
  • Build your first block — create a checklist block in Block Studio, preview it, publish it privately, and insert it into a document in about five minutes.
  • Anatomy of a block — understand defineBlock, BlockRenderProps, manifest fields, and project structure.
  • Develop and debug — learn how Block Studio preview differs from placed document blocks, how read-only mode works, and how to troubleshoot common errors.
  • How blocks run — see how SDK React blocks, standalone React apps, and cross-site HTML frames on rb-<hash>.orbixblocks.com isolate execution.

Documentation map

Every page and section in the SDK documentation is linked below. Click any node to open that page or jump to a section:

On this page