Development and Testing
Install the monorepo, run Vite+ and Vitest checks, and work on the sample plugins.
This guide covers contributing to the streamdeck-react repository. Run commands from the repository root unless a directory is specified.
Setup
Use Node.js 24.11 or newer within the 24.x release line, matching the repository's CI runtime. The root package.json pins the pnpm version.
pnpm install --frozen-lockfileVite+ includes Vitest. Import test APIs from vite-plus/test; no separate Vitest installation is needed. The commands below use pnpm exec vp so a global Vite+ installation is optional.
Run the tests
pnpm testThe root test script runs package and sample suites through Turborepo. It builds the library before the basic and coordinator sample integration tests, which import the built library.
To invoke Vitest directly, build the library first:
pnpm --filter @fcannizzaro/streamdeck-react build
pnpm exec vp testTest projects are defined in the root vite.config.ts:
| Project | Coverage |
|---|---|
streamdeck-react | Library behavior, rendering, hooks, adapters, worker packaging, and fuzz tests |
create-streamdeck-react | Scaffolder templates |
sample-basic | Native window creation and cleanup races |
sample-coordinator | Dial wrapping, persisted channel initialization, and recycled roots |
sample-snake | Food placement on nearly full and full boards |
sample-weather | Forecast timezones, request replacement, scrolling, and error recovery |
Select a project or enable watch mode:
pnpm exec vp test --project sample-weather
pnpm exec vp test watch --project streamdeck-reactvp test performs a single run by default. vp run test runs the repository's test script, including its build prerequisites.
Write a test
Co-locate tests with the code they exercise, using *.test.ts or *.test.tsx. Follow the existing __tests__ directories where present.
import { expect, test } from "vite-plus/test";
import { calcSize } from "@fcannizzaro/streamdeck-react";
test("scales a 144px design to a 72px key", () => {
expect(calcSize(72, 72).scale(24)).toBe(12);
});Use Vitest's vi.fn(), vi.spyOn(), and module mocks for test doubles. The library project runs in Happy DOM and loads packages/streamdeck-react/test-setup.ts for React's act() environment and DOM cleanup. The other projects run in Node.
Sample integration tests use a fake adapter and renderer to exercise library events without connecting to hardware. Passing tests do not verify physical device rendering or native window behavior on every platform. Use the MCP guide for interaction tests against a running plugin.
Type, lint, and format checks
Build before the first workspace type check so imports between packages can resolve their generated declarations. CI uses the same order:
pnpm build
pnpm typecheckWorkspace type checks use the repository's tsrs compiler. vp check checks formatting, lint rules, and types, including the separate docs app. Prepare that app before running the full repository check:
cd docs
bun install --frozen-lockfile
bun run types:check
cd ..
pnpm exec vp checkThe docs app maintains its own Bun lockfile. Its types:check script generates the Fumadocs collections and Next.js route types before checking TypeScript. Rerun it after adding or moving docs routes.
To format changes, run pnpm exec vp fmt <paths>. Review the diff before committing; the pre-commit hook also runs vp check --fix on staged files.
Build and run samples
pnpm --filter sample-basic build
pnpm --filter sample-basic devThe development command watches the sample build. Link its .sdPlugin directory with the sample's link script to run it in Stream Deck. Each sample uses a distinct Node inspector port, so multiple sample plugins can be debugged together.