Skip to Content
OrbixDocs
Block SDK · Concepts

Block lifecycle

How Orbix identifies block instances on a page, handles React StrictMode remounts, and cleans up per-block resources.

A single Orbix document can contain multiple instances of the same block type side by side — for example, three separate acme.timer blocks in one meeting note. Orbix isolates state, ports, capabilities, and disposable resources per mounted instance.

Block type ID vs instance ID

Every mounted block has two distinct identifiers:

  • Block type ID (manifest.id) — identifies the definition registered with defineBlock (for example 'acme.timer'). Shared by every copy of that block.
  • Block instance ID (blockId) — identifies one specific block placed in a document (for example 'blk_9f3a2c'). Stored on props.block.id and provided through React context.

Reading instance context (useBlockId and useOrbixBlockInstance)

Inside any component or custom hook rendered within a block, read identity from React context rather than global window variables:

src/InstanceInfo.tsx
import {
  useBlockId,
  useOrbixBlockInstance,
  orbixFetch,
} from '@orbixdocs/sdk';

export function InstanceBadge() {
  const blockId = useBlockId();
  const instance = useOrbixBlockInstance();
  const isReadOnly = instance?.isReadOnly ?? false;

  const ping = async () => {
    // Pass blockId explicitly to imperative helpers called outside render
    await orbixFetch('https://api.example.com/ping', { blockId });
  };

  return (
    <div>
      <code>Instance: {blockId}</code>
      <span>{isReadOnly ? ' (read-only)' : ' (editable)'}</span>
      <button type="button" onClick={() => void ping()}>
        Ping
      </button>
    </div>
  );
}

What happens outside a block context

If an SDK hook is called outside an OrbixBlockInstanceContext.Provider (for example in a raw unit test that mounted <MyComponent /> directly without renderBlock), useBlockId logs a single console.error and returns 'anonymous-block', which state, storage, and port APIs treat as a safe no-op.

When testing or building custom harnesses:

  • Prefer renderBlock(definition) in Vitest or mountBlockDevHarness(definition) in browser playgrounds — both wrap your component in OrbixBlockInstanceContext automatically.
  • If you mount a component tree yourself without a host, call enableStandaloneBlockHarness(true) before rendering so useBlockId resolves to 'standalone-dev-block'.

Mount, React.StrictMode, and unmount

When Orbix mounts a block on a page (DynamicBlockRenderer):

  1. Bind: The host binds blockId -> { type: manifest.id, preview } in capabilityEngine and wraps the subtree in OrbixBlockInstanceContext.Provider and BlockErrorBoundary.
  2. Effects: SDK hooks (useBlockOutput, useBlockInput, useBlockEvent, useCollaborative, useOrbixWebSocket) register listeners inside useEffect and clean them up in their effect return function.
  3. StrictMode safety: In development, React may run mount -> cleanup -> remount immediately to verify effect resilience. Never register ports, timers, WebSockets, or AudioContext instances during the render body — always create them inside useEffect so cleanup and re-registration stay balanced.
  4. Unmount: When the block is removed from the page or navigated away from, the host unbinds the instance from capabilityEngine, flushes or clears pending state patches, and calls blockResources.disposeAll(blockId).

Tracking custom resources (blockResources)

If your block opens imperative browser resources (such as a Worker, AudioContext, ResizeObserver, or WebGL context) outside standard React state, register a disposer with blockResources.trackFor(blockId, disposeFn) so Orbix guarantees cleanup when the block unmounts:

src/AudioPulse.tsx
import { useEffect } from 'react';
import { useBlockId, blockResources } from '@orbixdocs/sdk';

export function ResizeWatcher({ onWidth }: { onWidth: (w: number) => void }) {
  const blockId = useBlockId();

  useEffect(() => {
    const observer = new ResizeObserver((entries) => {
      const width = entries[0]?.contentRect.width;
      if (typeof width === 'number') onWidth(width);
    });
    observer.observe(document.body);

    // Track for host-level unmount safety; returns untrack() for early cleanup
    const untrack = blockResources.trackFor(blockId, () => {
      observer.disconnect();
    });

    return () => {
      observer.disconnect();
      untrack();
    };
  }, [blockId, onWidth]);

  return null;
}

blockResources guarantees:

  • Each registered disposer runs at most once, even if both your useEffect cleanup and blockResources.disposeAll(blockId) fire.
  • Disposers for a block run in LIFO (reverse registration) order, and an exception thrown by one disposer is caught and logged without skipping the remaining disposers.

On this page