@orchard/sdk

Core JavaScript SDK for building apps that run inside the Orchard platform.

The SDK provides a simple, framework-agnostic API for persistent state inside sandboxed iframes, without exposing any platform internals.

Features

• Persistent state via Orchard (no direct DB access)
• Framework-agnostic (works with vanilla JS, React, Vue, etc.)
• Local dev mode fallback (uses localStorage)
• Tiny, dependency-free core
• Secure by design (sandboxed iframe friendly)

Installation

npm install @orchard/sdk

The SDK is intended to be bundled into your app (Vite, Webpack, etc.). It is not meant to be loaded dynamically at runtime.

Quick Start

Create a persistent store

import { createStore } from "@orchard/sdk";

const store = createStore("state", { count: 0 });

store.subscribe((state) => {
  console.log("Current state:", state);
});

store.update((s) => ({ count: s.count + 1 }));

That's it.

• Inside Orchard → state persists via the platform
• Outside Orchard → state persists via localStorage

Concepts

Stores

A store represents a persistent JSON value scoped to:

• the current app instance
• a namespace you choose

const store = createStore(namespace, initialState);

• namespace must be a stable string (e.g. "state", "settings")
• initialState is used until persisted data is loaded

API

createStore(namespace, initialState?)

Creates (or returns) a store for the given namespace.

const store = createStore("state", { count: 0 });

Only one store exists per namespace.

store.get()

Returns the current state synchronously.

const state = store.get();

store.set(value)

Replace the entire state.

store.set({ count: 10 });

store.update(fn)

Update state based on the previous value.

store.update((prev) => ({
  ...prev,
  count: prev.count + 1,
}));

This is the recommended way to mutate state.

store.subscribe(fn)

Subscribe to state changes.

const unsubscribe = store.subscribe((state) => {
  console.log(state);
});

• The callback is called immediately with the current state
• Returns an unsubscribe function

Local Development Mode

When your app is not running inside Orchard, the SDK automatically falls back to localStorage.

You'll see a warning once:

[Orchard SDK] Running outside Orchard — using localStorage fallback.

This allows you to:

• develop apps locally
• preview behavior without Orchard
• reload without losing state

No code changes required.