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:
- Stateful & role-aware widgets — checklists, polls, approvals, and calculators that persist data with
useOrbixState, separate sharedteamvalues from per-viewerpersonalstate, and gate actions withuseBlockPermissions. - Multi-surface tools — blocks that render a compact inline card inside a document, a companion panel in split screen, and a dashboard in full-page mode via
<SurfaceRouter>anduseOrbixSurface. - Document & connected pipelines — outlines, template inserters, filter bars, and charts that inspect or edit page blocks with
useOrbixDocumentand exchange typed values throughuseBlockOutputanduseBlockInput. - API, AI, and realtime views — status cards, page summarizers, and multi-tab or WebRTC peer channels built with
useOrbixFetch,useOrbixAI, and@orbixdocs/sdk/realtime. - Canvas, workers, and zero-build HTML — Retina-scaled 2D/WebGL visuals and off-thread compute via
useOrbixCanvasanduseOrbixWorker, or standalone HTML and polyglot blocks wired with<orbix-*>custom elements.
Two ways to build
You can author blocks directly inside Orbix or develop against the @orbixdocs/sdk TypeScript package locally:
| Workflow | When to use it | How 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 path | Exports |
|---|---|
@orbixdocs/sdk | defineBlock, state, storage, document, workspace, database, ports, surfaces, permissions, network, secrets, canvas, workers, clipboard, file upload |
@orbixdocs/sdk/ui | Scope wrappers, Bento dashboard cards (BentoGrid, BentoCard, StatCard, Chart), EnvSetupCard, and Tailwind UI primitives (Button, Card, Badge, Input, Tabs, Dialog, Table) |
@orbixdocs/sdk/ai | useOrbixAI streaming and structured generation hook |
@orbixdocs/sdk/realtime | useCollaborative, realtimeEngine (broadcast, connectPeer, sse), useOrbixWebSocket |
@orbixdocs/sdk/testing | renderBlock, createMockBlockHost, property resolution helpers for Vitest / Testing Library |
@orbixdocs/sdk/dev | mountBlockDevHarness standalone local browser playground |
Minimal example
Every React SDK block calls defineBlock with a manifest and a component:
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.comisolate 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: