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 editingmanifest.jsonafter every line of code. - When placed in a document, the same block mounts with
preview: falseat thecommunitytrust tier. Only the community defaults plus capabilities declared inmanifest.capabilitiesare allowed.
If a block works in Studio Preview but throws SecurityCapabilityError after you publish and insert it into a page, check two things:
- Add the required capability array to
manifest.capabilities(for exampledocument: ['read', 'write']orstorage: ['local', 'persistent']). - 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 declarestorage: ['persistent']and omit'local',localstorage is no longer granted. Writestorage: ['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
useOrbixStatewrites are dropped and log a singleconsole.warnin the console. - Personal-scoped
useOrbixStatewrites ({ 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-installAvailable --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.tgzOnce installed, the template provides four scripts:
| Command | What it runs |
|---|---|
npm run dev | Starts Vite on http://localhost:4300 and mounts src/dev.tsx using mountBlockDevHarness. |
npm test | Runs Vitest (src/__tests__/block.test.tsx) in jsdom via renderBlock. |
npm run typecheck | Runs tsc --noEmit against @orbixdocs/sdk declarations. |
npm run build | Bundles 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 howteamstate andpersonalstate 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:
useOrbixFetchandorbixFetchfail closed when no host egress context is registered. Mockfetchin unit tests or test live network calls inside Orbix. - Local Dev Server modal: Block Studio's
•••menu includes a Local Dev Server option (defaulthttp://localhost:8080/dist/index.js) that polls a loopback URL (localhost,127.0.0.1, or[::1]) and loads an ES module withimport(). Note that the CLI template'snpm run devserves an HTML playground on port4300andnpm run buildoutputs 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
| Symptom | Cause | Fix |
|---|---|---|
UnknownSdkExportError when importing Button, Card, StatCard, or Tabs from @orbixdocs/sdk/ui | Block 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 document | Studio 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 registration | manifest.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 update | The 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 publishing | manifest.id starts with com.orbix.. | Change manifest.id to your own namespace (for example acme.my-block or my-block). |