Skip to Content
OrbixDocs
Block SDK · Getting started

Develop and debug

Iterate in Block Studio or locally, understand preview vs document permissions, and fix common errors.

This guide covers how day-to-day block development works, the differences between Block Studio's preview and a block placed in a real document, and how to set up local testing.

Iterating in Block Studio

Inside Block Studio, the top bar switches between three modes:

  • Chat — AI assistant for scaffolding or editing files in the current project.
  • Code — multi-file TypeScript/JSX/HTML editor.
  • Preview — live interactive preview of your block.

Use the Show Console button (terminal icon next to Save) to view compiler diagnostics, console.warn manifest lint messages, and runtime exceptions.

Preview permissions vs placed document blocks

This is the single most common source of surprises when developing a block:

  • In Block Studio Preview, your block mounts with authorPreview: true. The capability engine grants full author-level access so you can prototype hooks without editing manifest.json after every line of code.
  • When placed in a document, the same block mounts with preview: false at the community trust tier. Only the community defaults plus capabilities declared in manifest.capabilities are allowed.

If a block works in Studio Preview but throws SecurityCapabilityError after you publish and insert it into a page, check two things:

  1. Add the required capability array to manifest.capabilities (for example document: ['read', 'write'] or storage: ['local', 'persistent']).
  2. Remember that declaring a capability key replaces its community default for that key. For example, community blocks get storage: ['local', 'cache'] by default; if you declare storage: ['persistent'] and omit 'local', local storage is no longer granted. Write storage: ['local', 'persistent'] instead.

See Permissions and capabilities for the full tier table.

Checking read-only mode

Documents can be viewed in read-only mode (shared links, locked pages, or viewers without edit access). When isReadOnly is true:

  • Team-scoped useOrbixState writes are dropped and log a single console.warn in the console.
  • Personal-scoped useOrbixState writes ({ scope: 'personal' }) continue to work so viewers can still switch tabs or filter their own view.

Always check props.isReadOnly (or useOrbixBlockInstance()?.isReadOnly) to disable edit controls in your UI rather than letting users click buttons that silently no-op.

Local CLI and standalone playground

You can scaffold a standalone TypeScript project with create-orbix-block:

npx create-orbix-block my-block --template basic --no-install

Available --template options are basic, bento, full, and advanced.

Current npm package status (@orbixdocs/sdk v3.0.0)

@orbixdocs/sdk on the public npm registry is currently at 1.0.0, while v3 templates depend on "@orbixdocs/sdk": "^3.0.0". Running npm install directly in a freshly scaffolded folder will fail with ETARGET until 3.0.0 is published to npm. To use v3 locally today, pack or link packages/sdk from an Orbix checkout:

# In your orbix repo checkout:
npm run build:sdk
cd packages/sdk && npm pack

# In your block project:
npm install /path/to/orbix/packages/sdk/orbixdocs-sdk-3.0.0.tgz

Once installed, the template provides four scripts:

CommandWhat it runs
npm run devStarts Vite on http://localhost:4300 and mounts src/dev.tsx using mountBlockDevHarness.
npm testRuns Vitest (src/__tests__/block.test.tsx) in jsdom via renderBlock.
npm run typecheckRuns tsc --noEmit against @orbixdocs/sdk declarations.
npm run buildBundles the block with Vite.

What the local playground simulates (and what it does not)

mountBlockDevHarness from @orbixdocs/sdk/dev renders your block in a standalone browser page with:

  • Switchable themes (obsidian, paper, ivory, frost), surfaces (block, fullpage, sidebar_panel), and a read-only toggle.
  • Optional side-by-side dual-instance rendering (initialDualCollaborator: true) so you can verify how team state and personal state behave across two mounted views.
  • Mock pages (createMockPages) for basic document and workspace hook testing, plus a JSON state/manifest inspector.

Limitations compared to the real Orbix workspace:

  • CSS variables: The dev playground injects 9 core --orbix-* variables (--orbix-shell-bg, --orbix-surface-bg, --orbix-card-bg, --orbix-subtle-bg, --orbix-subtle-hover, --orbix-surface-border, --orbix-text-primary, --orbix-text-secondary, --orbix-accent). Always include fallback values for secondary tokens (var(--orbix-card-hover, #1f2026)).
  • Outbound network: useOrbixFetch and orbixFetch fail closed when no host egress context is registered. Mock fetch in unit tests or test live network calls inside Orbix.
  • Local Dev Server modal: Block Studio's ••• menu includes a Local Dev Server option (default http://localhost:8080/dist/index.js) that polls a loopback URL (localhost, 127.0.0.1, or [::1]) and loads an ES module with import(). Note that the CLI template's npm run dev serves an HTML playground on port 4300 and npm run build outputs a UMD bundle (dist/bundle.js), so CLI projects do not hot-reload directly into Studio via that modal. Copy or import your source into Block Studio when you are ready to test inside a real workspace document.

Troubleshooting common errors

SymptomCauseFix
UnknownSdkExportError when importing Button, Card, StatCard, or Tabs from @orbixdocs/sdk/uiBlock Studio maps @orbixdocs/sdk/* to the host core module, which does not include the npm Tailwind UI components.Use standard HTML elements styled with --orbix-* variables, or import @/components/ui/button when authoring exclusively in Block Studio.
SecurityCapabilityError only after inserting a published block into a documentStudio Preview runs with authorPreview: true, whereas document instances enforce community tier capabilities.Add the missing capability array (e.g. document: ['read', 'write']) to manifest.capabilities and republish.
[OrbixSDK:SDK_VERSION_MISMATCH] on registrationmanifest.sdk specifies a range incompatible with 3.0.0 (such as ^2.0.0).Update manifest.sdk to "^3.0.0".
useOrbixState logs an error and does not updateThe component was rendered outside an Orbix block context without enabling the standalone harness.Render via renderBlock(block) in tests or mountBlockDevHarness(block) in a standalone app (or call enableStandaloneBlockHarness(true) before mounting manually).
ReservedNamespaceError (RESERVED_NAMESPACE) when publishingmanifest.id starts with com.orbix..Change manifest.id to your own namespace (for example acme.my-block or my-block).

On this page