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.
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. |
--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 |
|---|---|
config.schema.json | Basic Homebridge Config UI schema and generated plugin alias. |
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, engine ranges, keywords, and local scripts. |
With --custom-ui, Nova also writes src/config-ui/server.ts and homebridge-ui/public/. The build copies those browser assets into build/config-ui/public, matching the customUiPath written to config.schema.json.
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.