@stackable-labs/sdk-extension-host 1.1.0 → 1.3.0

package/README.md

@@ -45,6 +45,109 @@ function App() {
 - **`CapabilityRPCHandler`** — handles capability requests from extension sandboxes
 - **`SandboxManager`** — creates and destroys hidden iframe sandboxes per extension
 
+## Building a local preview host
+
+During extension development, you can create a lightweight preview host app in your extension repo to test your extension against the real SDK sandbox — no private monorepo required.
+
+### Structure
+
+```
+packages/
+├── extension/          ← your extension
+└── preview/            ← local preview host
+    └── src/
+        ├── main.tsx
+        ├── App.tsx
+        └── mockData.json
+```
+
+### Preview App.tsx pattern
+
+```tsx
+import { ExtensionProvider, ExtensionSlot } from '@stackable-labs/sdk-extension-host';
+import type { CapabilityHandlers } from '@stackable-labs/sdk-extension-host';
+import { hostComponents } from '@stackable-labs/embeddables/components';
+import type {
+  ApiRequest,
+  ExtensionRegistryEntry,
+  Permission,
+  ToastPayload,
+} from '@stackable-labs/sdk-extension-contracts';
+import manifestRaw from '../../extension/public/manifest.json';
+import mockData from './mockData.json';
+
+const manifest = {
+  ...manifestRaw,
+  permissions: manifestRaw.permissions as Permission[],
+};
+
+const extensions: ExtensionRegistryEntry[] = [
+  {
+    id: manifest.name.toLowerCase().replace(/\s+/g, '-'),
+    manifest,
+    bundleUrl: `http://localhost:${import.meta.env.VITE_EXTENSION_PORT || '5173'}`,
+    enabled: true,
+  },
+];
+
+const mockContext = { customerId: 'cust_123', customerEmail: 'dev@example.com' };
+
+const capabilityHandlers: CapabilityHandlers = {
+  'data.query': async (payload: ApiRequest) => {
+    // return mock data based on payload.action
+    return mockData;
+  },
+  'actions.toast': async (payload: ToastPayload) => {
+    console.log('[Preview] toast:', payload);
+  },
+  'context.read': async () => mockContext,
+};
+
+export default function App() {
+  return (
+    <ExtensionProvider
+      extensions={extensions}
+      components={hostComponents()}
+      capabilityHandlers={capabilityHandlers}
+    >
+      {manifest.targets.map((target) => (
+        <ExtensionSlot key={target} target={target} context={mockContext} />
+      ))}
+    </ExtensionProvider>
+  );
+}
+```
+
+### Wiring two dev servers with Turborepo
+
+At the workspace root, add:
+
+**.env**
+```
+VITE_EXTENSION_PORT=5173
+VITE_PREVIEW_PORT=5174
+```
+
+**turbo.json**
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "globalEnv": ["VITE_EXTENSION_PORT", "VITE_PREVIEW_PORT"],
+  "tasks": {
+    "dev": { "cache": false, "persistent": true }
+  }
+}
+```
+
+Run both servers with one command:
+```bash
+pnpm dev
+```
+
+Extension runs at `:5173`, preview host at `:5174`. The preview host loads the extension bundle from the dev server, so edits to the extension hot-reload in the preview automatically.
+
+See [sample-extension-commerce](https://github.com/agnostack/sample-extension-commerce) and [sample-extension-approvals](https://github.com/agnostack/sample-extension-approvals) for complete working examples.
+
 ## Changelog
 
 See [npm version history](https://www.npmjs.com/package/@stackable-labs/sdk-extension-host?activeTab=versions).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackable-labs/sdk-extension-host",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -12,7 +12,7 @@
     }
   },
   "dependencies": {
-    "@stackable-labs/sdk-extension-contracts": "1.1.0",
+    "@stackable-labs/sdk-extension-contracts": "1.3.0",
     "@remote-dom/core": "1.x",
     "@remote-dom/react": "1.x"
   },