storybook-live-code-sandbox

storybook-live-code-sandbox provides one persistent composition workspace for Storybook. Stories send their displayed source to a dedicated sandbox story; individual previews do not mount drawers, launchers, or sandbox providers.

The package is design-system agnostic. It ships core behavior, a default artifact, and a Crossroads UI adapter contract without depending on Crossroads UI.

Install

npm install storybook-live-code-sandbox

Dedicated Sandbox Story

Create one full-screen Storybook story and keep live component references in the preview runtime:

import type { Meta, StoryObj } from "@storybook/react-vite";
import { LiveCodeSandboxProvider } from "storybook-live-code-sandbox";
import { addons } from "storybook/preview-api";
import "storybook-live-code-sandbox/styles.css";
import { liveCodeRegistry } from "../src/liveCodeRegistry";
import { liveCodeScope } from "../src/liveCodeScope";

function Workspace() {
  return (
    <LiveCodeSandboxProvider
      channel={addons.getChannel()}
      checkpointInterval={5}
      historyLimit={8}
      registry={liveCodeRegistry}
      scope={liveCodeScope}
      storageKey="my-library-live-code-sandbox"
    />
  );
}

const meta = {
  title: "Tools/Live Sandbox",
  parameters: { layout: "fullscreen" },
  render: () => <Workspace />
} satisfies Meta;

export default meta;
export const Sandbox: StoryObj<typeof meta> = {};

Add Story Source

Use the exact source string already resolved by Storybook's Docs Canvas and pass it unchanged:

import { addStoryToSandboxStorage } from "storybook-live-code-sandbox/storage";

addStoryToSandboxStorage({
  channel: addons.getChannel(),
  code: sourceProps.code,
  storageKey: "my-library-live-code-sandbox",
  storyName: story.name
});

The helper inserts at the saved cursor, creates an immediate Added <story> checkpoint, and broadcasts a storage-key-scoped synchronization event. It does not navigate to or open the sandbox. Empty source or unavailable storage throws without changing the workspace.

Manager links can navigate to the shared host in response to the exported event:

import { LIVE_CODE_SANDBOX_OPEN_EVENT } from "storybook-live-code-sandbox/events";

Preview-side links can request that navigation with requestLiveCodeSandboxOpen(channel).

Registry

export type LiveCodeRegistryItem = {
  name: string;
  importPath?: string;
  description?: string;
  category?: string;
  disabledReason?: string;
  sandboxVisible?: boolean;
  examples: Array<{ name: string; code: string; description?: string }>;
  props?: Array<{
    name: string;
    type?: string;
    required?: boolean;
    defaultValue?: string;
    description?: string;
    importance?: "high" | "normal" | "advanced";
  }>;
  metadata?: Record<string, unknown>;
};

Only entries with sandboxVisible: true appear. Categories create single-select filters; categories with fewer than three visible components are combined under Other. Props are ordered required, high, normal, advanced, then alphabetically.

Configuration

• scope: names available to react-live while evaluating compositions.
• registry: visual components, insertion examples, availability, and prop metadata.
• storageKey: namespace for persisted state and synchronization events.
• initialCode: optional initial content; the default is empty.
• checkpointInterval: component/prop insertions per automatic checkpoint. Default 5; 0 disables interval checkpoints.
• historyLimit: retained checkpoints. Default 8; constrained to 1-50.
• channel: optional Storybook-compatible channel for cross-frame synchronization.
• ui: optional LiveCodeSandboxUIAdapter.

Typing checkpoints on blur, paste checkpoints immediately, and story-source transfers checkpoint immediately. Reset remains in the dedicated view and clears code, history, undo/redo state, insertion progress, selection, and pending typing.

UI Artifacts

The default artifact uses the package's accessible fallback controls:

import { defaultLiveCodeSandboxArtifact } from "storybook-live-code-sandbox/artifacts/default";

Design systems can supply render functions for buttons, chips, fields, tabs, dialogs, notifications, and the root surface. The Crossroads export applies the artifact identity while receiving components through an adapter, avoiding a package dependency cycle:

import { createCrossroadsUIArtifact } from "storybook-live-code-sandbox/artifacts/crossroads-ui";

export const artifact = createCrossroadsUIArtifact(crossroadsAdapter);

Persistence

Storage version 3 persists code, cursor, last successful preview code, checkpoints, checkpoint interval, history retention, and insertion progress. Existing version 1 and version 2 data is migrated when read. Browser storage events and scoped channel events keep Docs frames, tabs, and the dedicated preview synchronized.

Release Process

1. Run npm run release:check.
2. Install the generated tarball in a consuming Storybook.
3. Complete manual desktop and mobile testing.
4. Publish only after explicit approval. Do not combine validation with versioning or publication.