Skip to content
Macro DeckMacro Deck Docs

Samples and template

Start from the template; read the samples. Both live in their own repositories, not in the Macro Deck repository.

Repository Use it when
Macro-Deck-Plugin-Template You are starting a plugin.
Macro-Deck-Sample-Plugins You want to see a capability implemented end to end.

The template

Section titled “The template”
Terminal window
macrodeck-plugin new --name "My Plugin" --id com.example.my-plugin --publisher "Example" --yes
MyPlugin/
├── MyPlugin.slnx
├── Directory.Build.props        net10.0, nullable, analyzers for every project
├── Directory.Packages.props     one MacroDeckSdkVersion for every Macro Deck package
├── NuGet.config                 nuget.org plus an empty local-feed/
├── src/MyPlugin/
│   ├── manifest.json
│   ├── macrodeck-build.json     one self-contained publish per platform
│   ├── MyPlugin.csproj
│   ├── Program.cs               CreatePlugin, logging, localization, one integration
│   ├── PluginIntegration.cs     IPluginIntegration with one action
│   ├── LogMessageAction.cs      the example action - replace it
│   ├── Localization/Strings.resx
│   ├── Assets/icon.svg          replace with your icon
│   └── Properties/launchSettings.json   "Macro Deck - Real Host" debug profile
└── tests/MyPlugin.Tests/        NUnit tests on MacroDeck.Plugin.Testing

Every file in src/MyPlugin/ is explained in Project setup. new installs the template if needed, fills in publisher, license, repository and homepage, and writes only the platforms you pick - see macrodeck-plugin new.

Without the CLI, use the template directly:

Terminal window
dotnet new install "MacroDeck.Plugin.Templates@*-*"
dotnet new macrodeck-plugin -n Acme.LightControl -o Acme.LightControl \
  --pluginId com.acme.light-control --pluginName "Acme Light Control"

@*-* picks the newest prerelease template. -o creates the directory; leave it out only when you are already in the project directory. Cloning the template repository and renaming by hand also works; its README has the rename checklist.

The samples

Section titled “The samples”

Each sample is one self-contained plugin, laid out exactly as new scaffolds a project. None needs an external service, credentials or network access.

Sample Demonstrates
Weather The smallest complete plugin: plain and dynamic-options actions, read-only and writable variables, an event, a one-step config flow, a weather provider, a second language (de).
Music player Transport, artwork, catalogue browsing, output devices, two instances with different capabilities, dynamic event options, action interaction pickers.
REST API A typed HttpClient through DI, a multi-step config flow with a secret and an OAuth branch, integration issues, notifications, API-backed variables and options.
Virtual profile A plugin-owned virtual profile with widget interactions, pushed variable updates, deck navigation, widget appearance, scripts and notifications.

The samples README has the full capability-by-sample matrix.

Run a sample

Section titled “Run a sample”
Terminal window
git clone https://github.com/Macro-Deck-App/Macro-Deck-Sample-Plugins
cd Macro-Deck-Sample-Plugins
dotnet build
dotnet test
Terminal window
macrodeck-plugin run --project src/MacroDeck.SampleWeatherPlugin --stub-host

Against a disposable stub host - no Macro Deck needed. To debug one against the desktop app, start its Macro Deck - Real Host launch profile - see Debugging plugins.

Terminal window
cd src/MacroDeck.SampleWeatherPlugin
macrodeck-plugin build --output ../../artifacts

Builds and packs every platform, like your own plugin.

Not in the samples

Section titled “Not in the samples”

Two things ship as packages in the Macro Deck SDK instead - reference them from your own test project:

  • MacroDeck.Plugin.Testing - loopback test host, fakes and assertions. See Testing plugins.
  • The conformance suite - macrodeck-plugin test, with stable check ids for CI. See Conformance.

See also

Section titled “See also”