@fcannizzaro/streamdeck-react

React primitives, hooks, and a custom renderer for building Stream Deck plugins with React across keys, dials, and touch surfaces.

Install

bun add @fcannizzaro/streamdeck-react react

Scaffolding

The fastest way to get started is with the create-streamdeck-react CLI:

bun create streamdeck-react
# or pnpm create streamdeck-react@latest# or npm create streamdeck-react@latest

It walks you through project setup — name, UUID, package manager, starter example — then optionally installs dependencies and links the plugin to Stream Deck.

Quick Start

Create an action:

import{useState}from"react";import{defineAction,useKeyDown,tw}from"@fcannizzaro/streamdeck-react";functionCounterKey(){const[count,setCount]=useState(0);useKeyDown(()=>{setCount((value)=>value+1);});return(<divclassName={tw("flex h-full w-full items-center justify-center bg-gradient-to-br from-[#0f766e] to-[#164e63] text-white",)}><spanclassName="text-[32px] font-bold">{count}</span></div>);}exportconstcounterAction=defineAction({uuid: "com.example.counter",key: CounterKey,});

Register it in your plugin entrypoint:

import{createPlugin,googleFont}from"@fcannizzaro/streamdeck-react";import{counterAction}from"./actions/counter.tsx";constinter=awaitgoogleFont("Inter");constplugin=createPlugin({fonts: [inter],actions: [counterAction],});awaitplugin.connect();

What You Get

• React-driven rendering for Stream Deck keys, dials, and touch layouts
• Hooks for key, dial, touch, lifecycle, SDK, and settings events
• Optional wrappers for shared providers and external state libraries
• Built-in primitives like Box, Text, Image, Icon, ProgressBar, and CircularGauge

Samples

• samples/basic/ — local state, persisted settings, dial interaction
• samples/zustand/ — shared state across keys via a module-scope Zustand store
• samples/jotai/ — shared atom state with a plugin-level Jotai Provider wrapper
• samples/pokemon/ — data fetching with TanStack Query and remote image rendering
• samples/animation/ — spring bounce, fade-slide, and spring dial animations
• samples/snake/ — snake game on the Stream Deck+ TouchStrip using dial controls and touch tap
• samples/weather/ — weather forecast dials with animated detail panels and a shared Zustand store

DevTools

A browser-based inspector for debugging plugins during development. Enable it in your plugin config:

constplugin=createPlugin({devtools: true,// ...});

Then open the hosted UI at streamdeckreact.fcannizzaro.com/devtools, or run a local copy:

npx @fcannizzaro/streamdeck-react-devtools

Panels include Console, Network, Elements (with on-device highlighting), Preview, and Events. All devtools code is automatically stripped from production builds.

Documentation

For setup guides, API reference, state-sharing patterns, and more examples, see:

https://streamdeckreact.fcannizzaro.com

License

MIT