Quickstart

This guide shows the minimum setup for a widget package using the SDK.

Important

Default to the ska-octopus-build-widgets scaffolder for new widgets. Use manual setup only when you need to diverge from the template.

1. Prerequisites

Node.js 18+
npm
A React widget project (Vite recommended)
Access to your GraphQL endpoint for local testing

2. Install the SDK

npm install @ska-octopus-widget-sdk/widget-sdk

Testing helpers are included in:

@ska-octopus-widget-sdk/widget-sdk/testing

3. Export a Widget Definition

Create src/index.ts and export a makeWidgetDef result:

import {
  INPUT_TANGO_ATTRIBUTES,
  INPUT_FORMATED_SCHEMA_TYPE,
  makeWidgetDef,
} from "@ska-octopus-widget-sdk/widget-sdk";
import MyWidget from "./MyWidget";

export const definition = makeWidgetDef({
  key: "my-widget",
  label: "My Widget",
  component: MyWidget,
  layout: { w: 6, h: 4, minW: 4, minH: 3 },
  polls: true,
  config: {
    schema: {
      type: "object",
      properties: {
        title: {
          type: INPUT_FORMATED_SCHEMA_TYPE,
          title: "Title",
          default: "",
        },
        attributes: {
          type: INPUT_TANGO_ATTRIBUTES,
          title: "Attributes",
          minItems: 1,
          default: [{ endpoint: "", attribute: "mid-cbf/subarray/01/healthstate" }],
        },
        useLiveData: {
          type: "boolean",
          title: "Use Live Data",
          default: true,
        },
      },
    },
  },
});

4. Run a Local Playground

Use the SDK dev harness to mirror host behavior:

import React from "react";
import ReactDOM from "react-dom/client";
import { createMockHost, DevProviders } from "@ska-octopus-widget-sdk/widget-sdk";
import MyWidget from "../src/MyWidget";

const host = createMockHost({
  httpUrl: "http://localhost:8000/graphql",
  wsUrl: "ws://localhost:8000/graphql",
});

ReactDOM.createRoot(document.getElementById("root")!).render(
  <DevProviders host={host}>
    <MyWidget instanceId="dev-widget-1" />
  </DevProviders>,
);

5. Validate Before Publishing

npm run lint
npm run test
npm run build