Writing a Module

A module is a plain ESM file that default-exports defineModule({ ... }). The same shape runs everywhere: a built-in lives at src/sandbox-builtins/<name>.ts inside this repo; a community module builds to a single self-contained ESM file that lands on disk at ~/.mutka/modules/<id>/index.js.

Scaffold a project (recommended)

The fastest way to start a community module is the published scaffolder. It generates a typed TypeScript project wired to the @mutka-explorer/module package, with a tsup build that outputs the single ESM file Mutka loads:

npm create @mutka-explorer@latest my-module

It prompts for the module id (author.name), display name, GitHub username, and permissions, then generates src/index.ts (a typed skeleton with a working command), a package.json with the build, and a mutka.config.json that points GitHub discovery at dist/index.js.

A minimal module

import { defineModule } from "@mutka-explorer/module";

export default defineModule({
  id: "author.my-module",
  name: "My Module",
  version: "1.0.0",
  description: "What it does, in one line.",
  icon: "data:image/png;base64,…",      // optional card image (data: or https URL)
  author: { name: "You", github: "you" }, // optional; defaults to the repo owner
  permissions: ["dialog"],              // declare every capability host.* uses
  commands: [
    {
      id: "author.my-module.hello",     // must start with the module ID
      label: "Say Hello",
      shortcut: "meta+shift+h",
      contextMenu: true,
      when: { selection: "any" },       // serializable visibility
    },
  ],
  setup(host) {
    host.onCommand("author.my-module.hello", async (snapshot) => {
      await host.dialog.confirm({
        message: `Hello from ${snapshot.currentDirectory}!`,
      });
    });
  },
});

Build it (npm run build in a scaffolded project) and the single ESM file in dist/ is what you publish. Prefer no runtime import at all? Use import type { SandboxModuleDef } from "@mutka-explorer/module" and annotate the definition — the same id inference with zero runtime import.

Display metadata

These optional fields control how your module appears in the Modules panel. They are source-agnostic — nothing here is specific to GitHub or any other host:

export default defineModule({
  id: "author.my-module",
  name: "My Module",
  version: "1.0.0",

  // Two equivalent ways to set an image — a hosted URL or an inline data URI:
  icon: "https://example.com/my-module.png",
  // icon: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",

  author: {
    name: "Ada Lovelace",
    link: "https://ada.example.com",          // clicking the name opens this
    avatar: "https://example.com/ada.png",    // or a data:image/... URI
  },

  tags: ["files", "viewer"],
  // ...
});

Images are rendered via <img src> only and the source is scheme-checked — any value that isn't an http(s) URL or a data:image/... URI is dropped, so there is no injection vector.

The host API (all async)

A command's handler receives a serializable snapshot of { selectedItems, orderedItems, currentDirectory, clipboard }.

The table above is just the basics. The full host surface also covers network, per-module storage, Keychain secrets, view/selection control, and the system integrations (Quick Look, "Open With", native drag-out) — see the capability reference for everything.

Beyond commands

A module isn't limited to commands and open handlers. It can contribute, each as its own declarative entry plus an optional setup hook:

• A whole virtual file system for a URI scheme (fileSystemProviders) — remote/cloud/archive storage.
• Declarative UI: side panels, settings sections, modals, forms, and status-bar items (panels, settingsSections, host.ui.*, host.statusbar.*).
• Custom list columns and file icons (columns, fileIcons).
• Left-sidebar "Places" entries (sidebarItems / host.sidebar.set).

Installing manually

After building your module (npm run build in a scaffolded project), copy the output file to the Mutka modules directory:

mkdir -p ~/.mutka/modules/author.my-module
cp dist/index.js ~/.mutka/modules/author.my-module/index.js

The module loads on next launch into its own isolated worker. During development you can also place modules in this repo's dev-modules/<id>/index.js — they are loaded through the same isolated worker path without a manual install step.

Module ID convention

What's next

• Permissions & capabilities — the full vocabulary
• Open handlers — claim a double-click
• Virtual file systems — serve a scheme
• Declarative UI — render panels and forms
• Columns & file icons — enrich the list
• Events & file watching — react to changes
• Storage, network & secrets
• Publishing a module — name a mutka-module-* repo and it's auto-discovered