From fec073c026cffe35d3058856a1be8554b93f626d Mon Sep 17 00:00:00 2001 From: The Allfather Date: Sun, 15 Feb 2026 00:21:10 -0500 Subject: [PATCH] Mudstack Plugin Boilerplate - initial commit --- .gitignore | 8 ++++ LICENSE | 21 +++++++++ README.md | 51 ++++++++++++++++++++- examples/context-menu-example/index.js | 24 ++++++++++ examples/context-menu-example/manifest.json | 25 ++++++++++ examples/context-menu-example/package.json | 15 ++++++ examples/hello-world/index.js | 15 ++++++ examples/hello-world/manifest.json | 12 +++++ examples/hello-world/package.json | 15 ++++++ index.js | 15 ++++++ manifest.json | 1 + package.json | 1 + 12 files changed, 202 insertions(+), 1 deletion(-) create mode 100644 .gitignore create mode 100644 LICENSE create mode 100644 examples/context-menu-example/index.js create mode 100644 examples/context-menu-example/manifest.json create mode 100644 examples/context-menu-example/package.json create mode 100644 examples/hello-world/index.js create mode 100644 examples/hello-world/manifest.json create mode 100644 examples/hello-world/package.json create mode 100644 index.js create mode 100644 manifest.json create mode 100644 package.json diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ef28c8b --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +node_modules/ +.env +*.log +dist/ +.DS_Store +Thumbs.db +.idea/ +.vscode/ diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..baa882d --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) Mudstack + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index ccbcf4b..bb5c0b1 100644 --- a/README.md +++ b/README.md @@ -1 +1,50 @@ -# mudstack-plugins +# Mudstack plugin template and examples + +Sample and boilerplate [Mudstack](https://www.mudstack.com) plugins. This repo is not part of the main Mudstack app; it helps you start or learn how to build plugins that run inside Mudstack (e.g. thumbnailers, context menu commands, custom integrations). + +- **[@mudstack/plugins on npm](https://www.npmjs.com/package/@mudstack/plugins)** – Types and base class for building plugins with IntelliSense. + +## Getting started (template) + +Start a new plugin by **forking this repo** or using **Use this template** (if enabled). The root of the repo is the plugin template. + +1. **Rename the plugin** in `manifest.json` and `package.json`: + - `manifest.json`: change `id`, `name`, `description`, `author`. + - `package.json`: change `name`, `description`, `author`. +2. Run **`yarn install`** or **`npm install`** in the repo root. +3. **Implement your logic** in `index.js`. Your class extends `MudstackPlugin` and has access to `this.api` (logging, events, db, config, etc.). See [@mudstack/plugins](https://www.npmjs.com/package/@mudstack/plugins) for the full API. +4. **Install the plugin** in Mudstack: copy this folder into your Mudstack plugins directory, or follow Mudstack’s plugin installation docs. + +You can add `dependencies`, `subscriptions`, and `registrations` in `manifest.json` as needed (see the `examples/` folder for reference). + +## Examples + +The `examples/` folder contains reference plugins you can learn from or try: + +- **hello-world** – Minimal plugin: logs on activate/deactivate and optionally subscribes to an event. +- **context-menu-example** – Adds a context menu command and handles the event when the user runs it. + +Use them as reference, or copy a folder into your Mudstack plugins directory to run them. + +## Directory layout + +``` +mudstack-plugins/ +├── README.md # This file +├── LICENSE +├── .gitignore +├── package.json # Template plugin (rename and customize) +├── manifest.json +├── index.js +└── examples/ + ├── hello-world/ + │ ├── package.json + │ ├── manifest.json + │ └── index.js + └── context-menu-example/ + ├── package.json + ├── manifest.json + └── index.js +``` + +Each plugin is a standalone folder (examples have their own `package.json`). Install dependencies inside the plugin folder you’re working on (repo root for the template, or an example folder). diff --git a/examples/context-menu-example/index.js b/examples/context-menu-example/index.js new file mode 100644 index 0000000..a017d1d --- /dev/null +++ b/examples/context-menu-example/index.js @@ -0,0 +1,24 @@ +const { MudstackPlugin } = require('@mudstack/plugins'); + +class ContextMenuExamplePlugin extends MudstackPlugin { + async activate() { + await super.activate(); + this.api.log('info', '[ContextMenuExample] Plugin activated'); + } + + async deactivate() { + this.api.log('info', '[ContextMenuExample] Plugin deactivating'); + await super.deactivate(); + } + + /** + * Called when the user runs the "Say Hello (example)" context menu command. + * Subscribed via manifest subscriptions (event + handler); no manual events.on() needed. + */ + async handleSayHello(message) { + const { id: requestId, payload } = message || {}; + this.api.log('info', '[ContextMenuExample] User ran the context menu command', payload); + } +} + +module.exports = ContextMenuExamplePlugin; diff --git a/examples/context-menu-example/manifest.json b/examples/context-menu-example/manifest.json new file mode 100644 index 0000000..812eae2 --- /dev/null +++ b/examples/context-menu-example/manifest.json @@ -0,0 +1,25 @@ +{ + "id": "com.mudstack.example.context-menu", + "name": "Context Menu Example", + "version": "1.0.0", + "description": "Adds a context menu command and handles the event when the user runs it", + "author": "Mudstack", + "main": "index.js", + "enabled": true, + "dependencies": [], + "subscriptions": [ + { + "event": "com.mudstack.example.context-menu.say-hello", + "handler": "handleSayHello" + } + ], + "registrations": [], + "contextMenuCommands": [ + { + "id": "com.mudstack.example.context-menu.say-hello", + "title": "Say Hello (example)", + "description": "Example context menu command from the context-menu-example plugin", + "eventType": "com.mudstack.example.context-menu.say-hello" + } + ] +} diff --git a/examples/context-menu-example/package.json b/examples/context-menu-example/package.json new file mode 100644 index 0000000..0f1a5a7 --- /dev/null +++ b/examples/context-menu-example/package.json @@ -0,0 +1,15 @@ +{ + "name": "mudstack-example-context-menu", + "version": "1.0.0", + "description": "Mudstack plugin example that adds a context menu command", + "main": "index.js", + "author": "Mudstack", + "license": "MIT", + "keywords": ["mudstack", "plugin", "example", "context-menu"], + "engines": { + "node": ">=16.0.0" + }, + "dependencies": { + "@mudstack/plugins": "^1.0.0" + } +} diff --git a/examples/hello-world/index.js b/examples/hello-world/index.js new file mode 100644 index 0000000..906de33 --- /dev/null +++ b/examples/hello-world/index.js @@ -0,0 +1,15 @@ +const { MudstackPlugin } = require("@mudstack/plugins"); + +class HelloWorldPlugin extends MudstackPlugin { + async activate() { + await super.activate(); + this.api.log("info", "[HelloWorld] Plugin activated"); + } + + async deactivate() { + this.api.log("info", "[HelloWorld] Plugin deactivating"); + await super.deactivate(); + } +} + +module.exports = HelloWorldPlugin; diff --git a/examples/hello-world/manifest.json b/examples/hello-world/manifest.json new file mode 100644 index 0000000..78025a4 --- /dev/null +++ b/examples/hello-world/manifest.json @@ -0,0 +1,12 @@ +{ + "id": "com.mudstack.example.hello-world", + "name": "Hello World Example", + "version": "1.0.0", + "description": "Minimal Mudstack plugin that logs on activate/deactivate", + "author": "Mudstack", + "main": "index.js", + "enabled": true, + "dependencies": [], + "subscriptions": [], + "registrations": [] +} diff --git a/examples/hello-world/package.json b/examples/hello-world/package.json new file mode 100644 index 0000000..cb0c6ce --- /dev/null +++ b/examples/hello-world/package.json @@ -0,0 +1,15 @@ +{ + "name": "mudstack-example-hello-world", + "version": "1.0.0", + "description": "Minimal Mudstack plugin example", + "main": "index.js", + "author": "Mudstack", + "license": "MIT", + "keywords": ["mudstack", "plugin", "example"], + "engines": { + "node": ">=16.0.0" + }, + "dependencies": { + "@mudstack/plugins": "^1.0.0" + } +} diff --git a/index.js b/index.js new file mode 100644 index 0000000..abfce65 --- /dev/null +++ b/index.js @@ -0,0 +1,15 @@ +const { MudstackPlugin } = require('@mudstack/plugins'); + +class MyPlugin extends MudstackPlugin { + async activate() { + await super.activate(); + this.api.log('info', 'MyPlugin activated'); + } + + async deactivate() { + this.api.log('info', 'MyPlugin deactivating'); + await super.deactivate(); + } +} + +module.exports = MyPlugin; diff --git a/manifest.json b/manifest.json new file mode 100644 index 0000000..a52514f --- /dev/null +++ b/manifest.json @@ -0,0 +1 @@ +{"id":"com.example.my-mudstack-plugin","name":"My Mudstack Plugin","version":"1.0.0","description":"A Mudstack plugin (rename me)","author":"","main":"index.js","enabled":true,"dependencies":[],"subscriptions":[],"registrations":[]} diff --git a/package.json b/package.json new file mode 100644 index 0000000..a58a651 --- /dev/null +++ b/package.json @@ -0,0 +1 @@ +{"name":"my-mudstack-plugin","version":"1.0.0","description":"A Mudstack plugin (rename me)","main":"index.js","author":"","license":"MIT","keywords":["mudstack","plugin"],"engines":{"node":">=16.0.0"},"dependencies":{"@mudstack/plugins":"^1.0.0"}}