Homebridge Plugin
Scaffold a Homebridge dynamic-platform plugin with the required registration entry point and Config UI schema.
Why Use This Command?
- Generates Homebridge's platform registration and cached-accessory hooks so the package begins with a valid plugin shape.
- Declares compatibility with Homebridge 1.11 and 2.x while using the current Homebridge types during development.
- Applies Nova's Homebridge TSConfig preset and npm package-name convention so framework and publication requirements stay aligned.
- Optionally adds the official Config UI X custom frontend and backend layout while keeping schema-rendered settings as the default.
- Includes built REPL and API-test starter commands with fixed-width Nova headers for local plugin development.
Requirements
- Node.js runtime — Use any Node.js LTS release.
- Homebridge environment — Install Homebridge when you want to load and test the generated plugin locally.
- Empty directory or monorepo root — Nova auto-detects whether to create a project or add a package.
Usage
Options
| Flag | Description |
|---|---|
-d, --dry-run | Run without writing any files. |
--install | Install dependencies after scaffolding; this is the default. |
--no-install | Skip dependency installation. |
--name <name> | Project slug when creating a new monorepo; omit at an existing root. |
--non-interactive | Use flags and defaults without opening prompts. |
--workspace-name <name> | Workspace directory name; Nova adds homebridge- to the npm package name. |
--output <dir> | Output directory. |
--custom-ui | Add Config UI X frontend assets and a custom UI server entry point. |
Output Files
| File | Description |
|---|---|
bin/ | Stable launchers for the installed REPL and API-test commands. |
config.schema.json | Basic Homebridge Config UI schema and generated plugin alias. |
src/cli/ | REPL, config-aware API-test starter, and shared CLI presentation. |
src/index.ts | Homebridge registration entry point. |
src/platform.ts | Dynamic platform class with cached-accessory restoration. |
tsconfig.source.json | Nova strict, Node.js, and Homebridge preset composition. |
package.json | Homebridge metadata, executable mappings, engine ranges, and local scripts. |
With --custom-ui, Nova also writes src/config-ui/server.ts and homebridge-ui/public/. The browser entry is an embeddable fragment rather than a competing HTML document, and it uses the Bootstrap styles injected by Homebridge instead of bundling another theme. Its responsive tabs introduce the generated plugin and demonstrate practical input, choice, and component patterns. A dedicated Open Homebridge Configuration action replaces the gallery with Homebridge's native schema form and a single return action, keeping the native and custom interfaces visually separate. The examples remain interactive without writing demonstration values into the user's configuration. The build copies those browser assets into build/config-ui/public, matching the customUiPath written to config.schema.json.
Local Utility Commands
Build the plugin before running either compiled utility:
npm run build --workspace "homebridge-lights"
npm run repl --workspace "homebridge-lights"
npm run test-api --workspace "homebridge-lights" -- --config ~/.homebridge/config.json
The REPL exposes the generated platform class and package identifiers. The API-test starter validates that the selected Homebridge config contains the generated platform, then points to the source file where provider-specific requests belong. It deliberately does not invent an upstream API contract for the consumer.
Non-Interactive Mode
nova scaffold package homebridge --non-interactive --name my-plugin --workspace-name lights --output ./my-plugin
nova scaffold package homebridge --non-interactive --workspace-name lights --output ./packages/lights
nova scaffold package homebridge --non-interactive --workspace-name thermostat --output ./packages/thermostat --custom-ui
Naming and Registration
Nova prefixes the npm package name with homebridge- when needed, so workspace lights becomes package homebridge-lights. A name that already begins with homebridge- is preserved.
The workspace is registered with the package role and distributable policy. Without --custom-ui, Homebridge Config UI X renders the schema normally. Enable the option only when the plugin needs its own setup flow or richer settings interface.
Nova also registers a same-named file artifact containing the package metadata, launchers, compiled plugin, and configuration schema. The workspace build stays usable for local Homebridge development; the root artifact is the explicit publishable layout.