Getting Started

In this article you'll learn how to setup your development environment, create your first Stream Deck plugin, and test your plugin in Stream Deck.

Installation

Prerequisites

Developing plugins with the Stream Deck SDK requires:

• Node.js version 20 or higher.
• Stream Deck version 6.4 or higher.
• Stream Deck device.
• Text editor, VS Code is recommended.
• Terminal for accessing the Stream Deck command line interface (CLI).

Learn more about installing Node.js.

Installing Node.js is best achieved with a Node version manager, such as:

• nvm for macOS
• nvm-windows for Windows

With one of the aforementioned nvm(-windows) installed, run the following commands:

1. Install Node.js:

   Terminal

   nvm install 20

2. Switch to the installed version of Node.js:

   Terminal

   nvm use 20

3. Restart your terminal and verify the version of Node.js is at least version 20:

   Terminal

   node -v

info

For more information on installing Node.js on Windows, we recommend Microsoft's how-to Install Node.js on Windows, or Node.js' download page.

Stream Deck

If you do not own a Stream Deck device, you can try Stream Deck Mobile for free.

Setup Wizard

The Stream Deck SDK is supported by a CLI, called the Stream Deck CLI. As part of the Stream Deck CLI, there is a command line plugin creation wizard for easily scaffolding a basic Stream Deck plugin.

First, install the Stream Deck CLI by running the following command.

npm

Terminal

npm install -g @elgato/cli

yarn

Terminal

yarn global add @elgato/cli

pnpm

Terminal

pnpm add -g @elgato/cli

Then, run the create command:

Terminal

streamdeck create

Plugin UUID

Your plugin's UUID is a reverse-DNS format string, unique to your plugin, that reflects your organization and the product your plugin is intended for, for example:

• com.obsproject.obs-studio
• com.youtube.live
• tv.twitch.studio

Plugin UUIDs must only contain lowercase alphanumeric characters (a-z, 0-9), hyphens (-), and periods (.).

Plugin UUID

Your plugin's UUID cannot be changed once it has been published on Marketplace.

File Structure

After completing the plugin creation wizard there will be a new directory, with the name of your plugin, that contains:

Plugin file structure

.
├── *.sdPlugin/
│   ├── bin/
│   ├── imgs/
│   ├── logs/
│   ├── ui/
│   │   └── increment-counter.html
│   └── manifest.json
├── src/
│   ├── actions/
│   │   └── increment-counter.ts
│   └── plugin.ts
├── package.json
├── rollup.config.mjs
└── tsconfig.json

.sdPlugin

The ./*.sdPlugin directory is your compiled plugin, and contains:

• bin, compiled output files from your ./src directory.
• imgs, supporting images distributed with your plugin.
• logs, logs generated with a logger.
• ui, property inspectors, allowing users to configure actions in Stream Deck.
• manifest.json, that defines the metadata of your plugin, learn more about the manifest.

src

The ./src directory contains the source file for your Stream Deck plugin and is configured to a Node.js environment. As part of the scaffolded plugin, the directory contains:

• index.ts, the entry point of your plugin.
• actions/increment-counter.ts, an example action that displays a count.

Running Your Plugin

In addition to your plugin files, the setup wizard will have pre-populated npm scripts in package.json to assist with building and developing your plugin:

Scripts provided in package JSON file

{
	"scripts": {
		"build": "rollup -c",
		"watch": "rollup -c -w --watch.onEnd=\"streamdeck restart {{YOUR_PLUGIN_UUID}}",
	},
	// ...
}

To start developing your plugin, run the following command:

Terminal

npm run watch

You should now see your plugin in Stream Deck.

Whilst running the npm run watch command, any changes you make to ./*.sdPlugin/manifest.json or ./src will automatically be reflected in Stream Deck. To stop watching for changes, press Ctrl + C.

Congratulations, you've just created your first Stream Deck plugin! 🎉

What's Next?

• Make your first changes.
• Learn more about actions and how you can expand your plugin's functionality.
• Discover property inspectors, allowing users to configure your plugin in Stream Deck.
• Explore more commands available within the Stream Deck CLI.