Plugin DevX — Quick Start

Create, develop, and build a custom widget plugin for Compose SDK.

Want to understand the plugin API in depth? See the Widget Plugins Tutorial for a progressive walkthrough of visualization, data fetching, design panels, and event handling.

Need the full CLI reference, all framework examples, or Fusion deployment? See the Plugin DevX Reference.

Prerequisites

• Node.js >= 20.19.0
• Compose SDK >= 2.30.0
• A Sisense instance:
  • For development: a URL and API token are needed for live data, but not required to start — you can develop the UI without them.
  • For deployment to Fusion: version 2026.2.2 or later is required.

1. Create a Plugin

npx @sisense/sdk-cli@latest create-plugin

The interactive prompt asks for a name and template:

? What name would you like to give the plugin? (my-custom-plugin) >
? How would you like to start?
> Empty Project
  Line Chart
  Simple Table

Use Empty to start from scratch, or Line Chart for a working reference implementation.

You can also skip prompts with flags:

npx @sisense/sdk-cli@latest create-plugin --name my-custom-chart --template line-chart

See the CLI Reference for all options.

2. Set Up Environment Variables

cd my-custom-chart
# npm
npm install
# yarn
yarn install

cp .env.local.example .env.local

Edit .env.local with your Sisense credentials:

VITE_APP_SISENSE_URL=https://your-instance.sisense.com
VITE_APP_SISENSE_TOKEN=your-api-token

Without these values, the dev server starts but shows a "Configuration required" warning instead of live data.

Note: To deploy the plugin to your Sisense Fusion instance, use an API token for a user with the 'Admin' role (see Step 7).

3. Start the Dev Server

# npm
npm run dev
# yarn
yarn dev

Opens at http://localhost:3000 with a split layout — your visualization on the left, design panel on the right:

Changes to files in src/ are reflected instantly via hot module replacement.

4. Edit Your Components

The two files you'll spend most time in:

src/components/Visualization.tsx — your visualization. Implements CustomVisualization with CustomVisualizationProps:

import type { CustomVisualization, CustomVisualizationProps } from '@sisense/sdk-ui';

import type { DataOptions, StyleOptions } from '../types.js';

export type VisualizationProps = CustomVisualizationProps<DataOptions, StyleOptions>;

export const Visualization: CustomVisualization<VisualizationProps> = ({
  dataSource,
  dataOptions,
  filters,
  styleOptions,
}) => {
  return <div>...</div>;
};

src/components/DesignPanels.tsx — style configuration UI. Implements DesignPanelProps:

import type { DesignPanelProps } from '@sisense/sdk-ui';

import type { StyleOptions } from '../types.js';

export const DesignPanels = ({ styleOptions, onChange }: DesignPanelProps<StyleOptions>) => {
  return <div>{/* your configuration controls */}</div>;
};

Edit src/dev-preview-props.ts to provide sample data that matches your DataOptions type.

Using an AI agent? The project includes a pre-configured .claude/ folder with reference docs readable by any AI coding agent. With Claude Code, run /design-custom-widget and describe your chart — the agent implements everything (data inputs, library, chart code, style controls) in one step. With other agents, describe your goal in plain language and reference the guides in .claude/docs/ directly. See AI-Driven Development for the full workflow.

5. Build

# npm
npm run build
# yarn
yarn build

Produces framework-aware outputs:

6. Register in Your App

Install the plugin (published to npm or from a local path):

# npm
npm install my-custom-chart
# yarn
yarn add my-custom-chart

# from local path (run build first)
# npm
npm install ./path/to/my-custom-chart
# yarn
yarn add file:./path/to/my-custom-chart

Then register it via the plugins prop. See WidgetPlugin for the full plugin object shape:

import { Dashboard, SisenseContextProvider } from '@sisense/sdk-ui';
import myPlugin from 'my-custom-chart';

function App() {
  return (
    <SisenseContextProvider
      url="https://your-instance.sisense.com"
      token="your-api-token"
      plugins={[myPlugin]}
    >
      <Dashboard title="My Dashboard" widgets={widgets} />
    </SisenseContextProvider>
  );
}

The customWidgetType in your widget config must match the name field in src/index.tsx.

For Vue and Angular integration, see the Framework Integration section in the reference.

7. Deploy to Sisense Fusion

Once your plugin is built, you can deploy it directly to a Sisense Fusion instance.

Make sure .env.local contains your Sisense URL and an API token for a user with the 'Admin' role (see Step 2), then run:

# npm
npm run deploy
# yarn
yarn deploy

This command builds the Fusion bundle (dist-fusion/plugin.zip) and uploads it to your instance in one step. After a successful deploy the plugin is available immediately — no manual upload needed.

For details on the Fusion bundle format, plugin.json metadata, and what the deploy script does under the hood, see Deploying to Sisense Fusion in the reference.

Next Steps

• AI-Driven Development — use an AI agent to build plugins faster: describe your goal in plain language and the agent implements everything in one step
• Widget Plugins Tutorial — learn the plugin API: visualization props, data fetching, data panel, design panel, event handling
• Plugin DevX Reference — full CLI options, project structure, testing, all framework examples, Fusion deployment