@fcannizzaro/streamdeck-react

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-lockfile

Vite+ 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 test

The 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 test

Test projects are defined in the root vite.config.ts:

ProjectCoverage
streamdeck-reactLibrary behavior, rendering, hooks, adapters, worker packaging, and fuzz tests
create-streamdeck-reactScaffolder templates
sample-basicNative window creation and cleanup races
sample-coordinatorDial wrapping, persisted channel initialization, and recycled roots
sample-snakeFood placement on nearly full and full boards
sample-weatherForecast 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-react

vp 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 typecheck

Workspace 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 check

The 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 dev

The 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.

On this page