@yolnoma/plugin-sdk

Official SDK for building Yolnoma plugins.

This is a Phase 1 architecture proof-of-concept.

It establishes the plugin contract between plugin developers and the Yolnoma runtime. It does not yet include the Yolnoma runtime, plugin installation, or .yplugin packaging.

---

Table of Contents

1. What are Yolnoma plugins?
2. What is this SDK?
3. Plugin structure
4. definePlugin()
5. Lifecycle
6. Navigation
7. Routes
8. JSON Validator example
9. What is NOT implemented yet

---

What are Yolnoma plugins?

Yolnoma is a desktop application (Tauri-based) that allows developers to extend its functionality through plugins.

Plugins are loaded from the local filesystem:

com.jksoftware.yolnoma-app/
└── plugins/
    ├── json-validator.yplugin
    └── my-custom-plugin.yplugin

A .yplugin is a packaged plugin bundle (similar to a ZIP). It contains compiled JavaScript, metadata, and assets.

Plugins are sandboxed and interact with Yolnoma through the Plugin API defined in this SDK.

---

What is this SDK?

This SDK defines the contract between plugin developers and the Yolnoma runtime:

Plugin
   ↕
@yolnoma/plugin-sdk     ← this package
   ↕
Yolnoma Plugin Runtime  ← implemented inside Yolnoma
   ↕
Yolnoma App

The SDK is a public package. The Yolnoma runtime is private and implements the SDK interfaces.

The SDK provides:

• definePlugin() — factory for defining a plugin
• PluginAPI — the interface the runtime provides to your plugin
• TypeScript types for everything

---

Plugin structure

my-plugin/
├── src/
│   ├── index.ts          ← plugin entry (must export default from definePlugin())
│   ├── pages/
│   │   └── MainPage.tsx
│   └── ...
├── package.json
└── tsconfig.json

The entry file must have a default export produced by definePlugin().

---

definePlugin()

import { definePlugin } from "@yolnoma/plugin-sdk";

export default definePlugin({
  // ── Manifest ──────────────────────────────────────────
  id: "com.example.my-plugin",       // Reverse-DNS unique ID
  name: "My Plugin",                 // Human-readable name
  version: "0.1.0",                  // Semantic version
  description: "Does something useful.",
  author: { name: "Jane Dev", email: "jane@example.com" },

  // ── Lifecycle ─────────────────────────────────────────
  activate(api) {
    // Register pages and navigation here
    api.router.addRoute({ path: "/", component: MainPage });
    api.navigation.addItem({ label: "My Plugin", path: "/" });
  },

  deactivate() {
    // Optional cleanup (remove listeners, cancel timers, etc.)
  },
});

Manifest fields

Field	Type	Required	Description
id	string	✓	Reverse-DNS unique identifier
name	string	✓	Human-readable display name
version	string	✓	Semantic version (e.g. "0.1.0")
description	string	—	Short description
author	string | object	—	Author name or { name, email?, url? }
entry	string	—	Entry file path in bundle (default: "index.js")
minYolnomaVersion	string	—	Minimum Yolnoma version required
permissions	string[]	—	Permissions the plugin requests
icon	string	—	Icon path relative to bundle root

---

Lifecycle

Yolnoma manages plugin lifecycle as follows:

load        → Yolnoma imports the plugin module
activate    → api.activate(pluginAPI) is called
               Plugin registers routes and navigation
deactivate  → api.deactivate() is called (if defined)
               Plugin cleans up resources

Your activate() function receives a PluginAPI object:

activate(api: PluginAPI) {
  // api.pluginId  → your plugin's ID
  // api.router    → RouterAPI
  // api.navigation → NavigationAPI
}

---

Navigation

Register sidebar items with api.navigation.addItem():

api.navigation.addItem({
  label: "My Plugin",   // Shown in sidebar
  path: "/",            // Plugin-relative path
  icon: <MyIcon />,     // Optional React element or URL string
});

Nested navigation:

api.navigation.addItem({
  label: "My Plugin",
  path: "/",
  children: [
    { label: "Dashboard", path: "/" },
    { label: "Settings",  path: "/settings" },
  ],
});

Paths are plugin-relative. Yolnoma mounts them under /plugin/<plugin-id>/:

/plugin/com.example.my-plugin/
/plugin/com.example.my-plugin/settings

---

Routes

Register pages with api.router.addRoute():

api.router.addRoute({
  path: "/",
  component: MainPage,
  meta: { title: "My Plugin" },
});

api.router.addRoute({
  path: "/settings",
  component: SettingsPage,
  meta: { title: "Settings" },
});

Lazy loading is supported:

api.router.addRoute({
  path: "/heavy-page",
  component: React.lazy(() => import("./pages/HeavyPage")),
});

---

JSON Validator example

See examples/json-validator/.

This plugin demonstrates the full SDK contract:

// examples/json-validator/src/index.tsx

import { definePlugin } from "@yolnoma/plugin-sdk";
import { ValidatorPage } from "./pages/ValidatorPage";

export default definePlugin({
  id: "com.jksoftware.json-validator",
  name: "JSON Validator",
  version: "0.1.0",
  description: "Validate and inspect JSON with precise error reporting.",
  author: { name: "JK Software" },

  activate(api) {
    api.router.addRoute({ path: "/", component: ValidatorPage });
    api.navigation.addItem({ label: "JSON Validator", path: "/" });
  },
});

The validator reports:

• ✓ Valid JSON for correct input
• ✕ Invalid JSON with line, column, and source excerpt for errors

Error example output:

✕ Invalid JSON
Trailing comma before '}'
Line 3, column 18
…"name": "Jasur",↵}…

---

What is NOT implemented yet

This is Phase 1. The following is intentionally out of scope:

Feature	Status
Yolnoma runtime (loading plugins at runtime)	Not implemented — in private Yolnoma repo
.yplugin packaging/bundling	Not implemented — planned in yolnoma-plugin-dev
Plugin installation UI / Workshop	Not implemented
Plugin Store / marketplace	Not implemented
Plugin permissions enforcement	Not implemented
Filesystem / network API for plugins	Not implemented
Hot reload / dev server	Not implemented
Plugin signing / copyright protection	Not implemented

These will be built incrementally in subsequent phases.

---

Repository structure

yolnoma-plugin-sdk/
├── src/
│   ├── index.ts              ← public API exports
│   ├── types/
│   │   ├── api.ts            ← PluginAPI, RouterAPI, NavigationAPI
│   │   ├── plugin.ts         ← PluginManifest, PluginDefinition
│   │   ├── navigation.ts     ← NavigationItem
│   │   └── router.ts         ← RouteDefinition
│   └── plugin/
│       └── definePlugin.ts   ← definePlugin() factory
│
├── examples/
│   └── json-validator/       ← proof-of-concept plugin
│       ├── src/
│       │   ├── index.tsx
│       │   ├── pages/
│       │   │   └── ValidatorPage.tsx
│       │   └── lib/
│       │       └── jsonValidator.ts
│       ├── package.json
│       └── tsconfig.json
│
├── package.json
├── tsconfig.json
└── README.md

---

License

MIT — JK Software