엘가토 스트림덱과 핫스팟 스트림독에서 동작되는 플러그인을 타입스크립트로 만들어본다. 타입스크립트를 사용하는 이유는 C# 개발에 익숙하고, 자바스크립트로 저장되기 때문에 호환성이 매우 좋으며, Node.js로 시스템 접근이 가능하며, 자바스크립트 데이터 형식인 JSON을 변환이나 정의 없이 즉시 사용할 수 있기 때문이다. 여기서는 스트림독을 기준으로 한다.(스트림독만 보유 중🤣)
개발 환경 준비
Visual Studio Code
https://code.visualstudio.com/
최신 버전을 설치한다.
Node.js
https://nodejs.org/ko/download
터미널(관리자)에서 winget install OpenJS.NodeJS 명령을 실행하거나 Windows 설치 프로그램으로 설치한다.
설치 후 다음 명령으로 버전을 확인할 수 있다.
> node -v
v25.5.0VSCode 확장 설치
- Korean Language Pack for Visual Studio Code: 한국어 팩
- Visual Studio Keymap: Visual Studio에 익숙해서
- npm Intellisense: npm 자동 완성
- Prettier – Code formatter: 코드를 예쁘게~
- Path Intellisense: 경로 자동 완성
- ESLint: 디버깅을 빠르게~
- Error Lens: 오류 강조
- Better Comments Next: 코멘트를 컬러풀하게~
터미널에서 다음 명령어를 실행하여 엘가토 명령줄 도구(CLI)를 설치한다.
> npm install -g @elgato/cli
changed 75 packages in 8s
13 packages are looking for funding
run `npm fund` for detailsnpm은 nodejs 설치에서 함께 설치되며, -g 옵션은 전역 설치이다. @는 조직 표시이고 엘가토의 cli 패키지를 설치하겠다는 것이다.
프로젝트 폴더로 이동 후 터미널에서 다음 명령을 실행한다.
> streamdeck create
___ _ ___ _
/ __| |_ _ _ ___ __ _ _ __ | \ ___ __| |__
\__ \ _| '_/ -_) _` | ' \ | |) / -_) _| / /
|___/\__|_| \___\__,_|_|_|_| |___/\___\__|_\_\
Welcome to the Stream Deck Plugin creation wizard.
This utility will guide you through creating a local development environment for a plugin.
For more information on building plugins see https://docs.elgato.com.
Press ^C at any time to quit.
? Author:
> Please enter the author.필요한 정보를 모두 입력한다.
UUID는 플러그인에서 사용될 도메인 이름을 거꾸로 입력한 것이다. 플러그인에는 여러 기능이 포함될 수 있으며 그 그룹에 대한 이름을 지정하는 것이다. 마켓 플레이스에 공개한 후에는 UUID를 변경하면 안 된다.
✔ Author: DevAny
✔ Plugin Name: MyPlugin
✔ Plugin UUID: kr.devany.myplugin
✔ Description: 테스트 플러그인
✔ Create Stream Deck plugin from information above? Yes
Creating MyPlugin...
✔ Enabling developer mode
✔ Generating plugin
✔ Installing dependencies
✔ Building plugin
✔ Finalizing setup
Successfully created plugin!
? Would you like to open the plugin in VS Code? (Y/n)Y를 입력하면 VSCode가 실행된다.

프로젝트 폴더 아래에 샘플 파일이 자동으로 생성된다.
컴파일
파일이 변경될 때마다 자동으로 컴파일을 하려면 터미널에서 다음 명령어를 실행한다.
>npm run watch
rollup v4.57.1
bundles src/plugin.ts → kr.devany.myplugin.sdPlugin/bin/plugin.js...
created kr.devany.myplugin.sdPlugin/bin/plugin.js in 911ms
watch.onEnd $ streamdeck restart kr.devany.myplugin
ℹ Stream Deck is not running. Starting Stream Deck.
[2026-02-03 17:05:10] waiting for changes...플러그인이 설치될 위치
프로젝트 폴더의 플러그인 폴더를 다음과 같은 경로에 복사한다.
Maker | Path |
|---|---|
엘가토 | %AppData%\Elgato\StreamDeck\Plugins\kr.devany.myplugin.sdPlugin |
핫스팟 | %AppData%\HotSpot\StreamDock\plugins\kr.devany.googleapi.sdPlugin\bin |
rollup.config.mjs
컴파일 대상 경로를 위 플러그인 폴더의 bin으로 지정하면 수동으로 복사할 필요가 없다.
rollup.config.mjs 파일을 열고 다음과 같이 sdPlugin 경로를 편집한다.
const sdPlugin = path.join(process.env.APPDATA, "Elgato/StreamDeck/Plugins/kr.devany.myplugin.sdPlugin");sourcemap
const isWatching = !!process.env.ROLLUP_WATCH;기본값은 위와 같이 설정되어 있으며, watch일 때에만 .map 파일이 생성된다. .map 파일에는 개인 정보가 포함되어 있으므로 git에 공개되지 않도록 한다. 파일이 필요 없으면 false로 설정한다.
이제 npm run watch를 실행할 때마다 해당 폴더에 컴파일된 파일이 생성되며, 스트림덱에서 즉시 테스트가 가능하다. bin이 아닌 폴더와 파일은 수동으로 복사해야 한다.
> npm run watch
rollup v4.57.1
bundles src/plugin.ts → kr.devany.myplugin.sdPlugin/bin/plugin.js...
created kr.devany.myplugin.sdPlugin/bin/plugin.js in 1s
watch.onEnd $ streamdeck restart kr.devany.myplugin
✔ Restarted kr.devany.myplugin
[2026-02-03 23:30:32] waiting for changes...위와 같은 상태에서 파일이 변경되면 package.json에서 설정한 watch 명령이 실행된다.
키에 플러그인 할당


⬆️핫스팟의 스트림독은 프로그램을 재시작 해야 적용된다.
오른쪽 플러그인 목록에 추가된 플러그인이 나타나며, 스트림독 화면으로 배치한 다음 버튼을 누를 때마다 아래와 같이 값이 증가하는 것을 볼 수 있다.

manifest.json
{
"Name": "MyPlugin",
"Version": "0.1.0.0",
"Author": "DevAny",
"Actions": [
{
"Name": "Counter",
"UUID": "kr.devany.myplugin.increment",
"Icon": "imgs/actions/counter/icon",
"Tooltip": "Displays a count, which increments by one on press.",
"PropertyInspectorPath": "ui/increment-counter.html",
"Controllers": [
"Keypad"
],
"States": [
{
"Image": "imgs/actions/counter/key",
"TitleAlignment": "middle"
}
]
}
],
"Category": "MyPlugin",
"CategoryIcon": "imgs/plugin/category-icon",
"CodePath": "bin/plugin.js",
"Description": "테스트 플러그인",
"Icon": "imgs/plugin/marketplace",
"SDKVersion": 2,
"Software": {
"MinimumVersion": "6.4"
},
"OS": [
{
"Platform": "mac",
"MinimumVersion": "12"
},
{
"Platform": "windows",
"MinimumVersion": "10"
}
],
"Nodejs": {
"Version": "20"
},
"UUID": "kr.devany.myplugin"
}Actions[]->UUID 값은 스트림독 버튼에 할당한 기능에 대한 고유 이름이다. 다른 기능을 하는데 UUID가 같으면 오동작하므로 이름을 신중하게 지정해야 한다.
Software->MinimumVersion 값은 스트림독(3.10.197.1210)에 영향을 주지 않는다.
plugin.ts
SDK 기본값일 뿐이다. 보통은 index.ts로 이름을 지어야 시작 파일을 구분하기 쉽다.
import streamDeck from '@elgato/streamdeck';
import { IncrementCounter } from './actions/increment-counter';
streamDeck.logger.setLevel('trace');
streamDeck.actions.registerAction(new IncrementCounter());
streamDeck.connect();엘가토/스트림덱 패키지에는 윈소켓과 통신 관련 코드가 포함되어 있으므로 매우 깔끔하게 코딩할 수 있다.
Logger는 플러그인 폴더\logs\ 로그를 기록하는 기능을 한다. 스트림독에서도 동작한다.
