Build your first plugin

This walkthrough creates a minimal plugin and runs it locally.

Prerequisites

• Dot X app running (starts the local plugin server on port 3001)
• Node 16+ or Deno 1.41+

Scaffold with the CLI (recommended)

The easiest way to create a new plugin is with the interactive scaffolder:

npx @dotmatrixlabs/create-dotx-plugin

The TUI walks you through choosing a name, ID, and runtime (Deno or Node). A project folder is created automatically based on the plugin ID.

CLI flags (for CI / automation)

npx @dotmatrixlabs/create-dotx-plugin --name "My Plugin" --node

• --name <name>: Plugin display name
• --id <id>: Override the generated plugin ID (kebab-case)
• --deno (default): Deno + TypeScript template
• --node: Node + TypeScript + esbuild template with <plugin-name>.dotxplugin packaging
• --force: Overwrite existing files

Manual setup (Node)

If you prefer to set up manually:

1. Create a folder and initialise it:

mkdir my-plugin && cd my-plugin
npm init -y
npm install @dotmatrixlabs/dotx-plugin-sdk
npm install -D esbuild

2. Create manifest.json:

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "0.1.0",
  "description": "My first Dot X plugin",
  "author": "Your Name",
  "dotxVersion": ">=2.0.0",
  "permissions": [],
  "main": "main.js"
}

3. Create main.ts:

import Plugin, { runPlugin } from "@dotmatrixlabs/dotx-plugin-sdk";

class MyPlugin extends Plugin {
  async onLoad() {
    await this.ui.showToast({ message: "Hello from plugin!", type: "success" });
  }
}

if (require.main === module) {
  runPlugin(MyPlugin);
}

4. Add a build script to package.json:

{
  "scripts": {
    "build": "esbuild main.ts --bundle --outfile=main.js --format=cjs --platform=node --target=node16 --minify",
    "start": "node main.js"
  }
}

5. Build and run:

npm run build
npm start

Manual setup (Deno)

1. Create manifest.json (same as above, set "main": "main.ts").

2. Create main.ts:

import Plugin, { runPlugin } from "npm:@dotmatrixlabs/dotx-plugin-sdk";

class MyPlugin extends Plugin {
  async onLoad() {
    await this.ui.showToast({ message: "Hello from plugin!", type: "success" });
  }
}

runPlugin(MyPlugin);

3. Add deno.json:

{
  "tasks": { "start": "deno run --allow-all main.ts" },
  "nodeModulesDir": "auto"
}

4. Run:

deno task start

What happens

When the plugin starts, it connects to the Dot X plugin server, registers itself using manifest.json, and calls your onLoad() method. You should see a toast notification in the app.

Next steps

• Add a settings page — see the SettingsBuilder Components reference
• Persist data with this.config — see Plugin Config
• React to device changes — see Events & Communication
• Check out more Examples