companion-config

Define and validate Bitfocus Companion module configuration fields using @companion-module/base.

Updated May 19, 2026
One-click install
npx skills add https://github.com/digitaldrummerj/bitfocus-companion-skills --skill companion-config-digitaldrummerj
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: companion-config
Source: https://github.com/digitaldrummerj/bitfocus-companion-skills/tree/main/plugins/companion-config
Command: npx skills add https://github.com/digitaldrummerj/bitfocus-companion-skills --skill companion-config-digitaldrummerj

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @companion-module/base.

What problem does it solve? Bitfocus Companion modules need typed, validated configuration fields for connection settings like host, port, and credentials, but choosing the right field types, validation rules, and configUpdated handling is error-prone. This Skill provides the patterns and API reference to implement module configuration correctly. ## Core Features & Use Cases - Config Field Definitions: Covers all SomeCompanionConfigField types including textinput, number, dropdown, multidropdown, checkbox, colorpicker, static-text, secret, bonjourdevice, and custom-variable. - Validation Patterns: Built-in Regex constants (IP, HOSTNAME, URL, SOMETHING) plus min/max constraints, required flags, and default values. - Lifecycle Handling: Guidance for configUpdated() to safely reconnect and refresh module state when settings change. - Use Case: When building a Companion module for a network device, use this Skill to add an IP address field with Regex.IP validation, a port number field with min/max bounds, and a secret field for the API key, then wire configUpdated() to reconnect on changes. ## Quick Start Ask the agent to add a host and port config field with validation to your Companion module.

Frequently Asked Questions about companion-config

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a config field to a Bitfocus Companion module?▼

Add a field object to the array returned by GetConfigFields() with an id, type, label, and width, then add a matching property to your ModuleConfig interface. Provide a default value so the field is never undefined on first initialization.

What config field types does @companion-module/base support?▼

The SomeCompanionConfigField union includes textinput, number, dropdown, multidropdown, checkbox, colorpicker, static-text, secret, bonjourdevice, and custom-variable. Each type has specific properties like choices for dropdowns or min/max for numbers.

How do I validate an IP address in a Companion config field?▼

Use the built-in Regex.IP constant from @companion-module/base on a textinput field's regex property. Other available constants include Regex.HOSTNAME, Regex.URL, Regex.NUMBER, and Regex.SOMETHING for non-empty strings.

Why is my Companion module not reconnecting after config changes?▼

The configUpdated() method must first assign this.config = config, then disconnect the existing connection and reconnect with the new values. Mark the method async and await connection changes so state updates complete before actions or feedbacks run.

Can Companion config fields be shown conditionally?▼

There is no built-in conditional field visibility in the config API. The common workaround is to include all fields with clarifying labels and handle the branching logic inside configUpdated() based on a dropdown selection like connection type.