LogoNotyra Docs
Plugins

Manifest

Every package.json field and the rules for feature and theme plugins

Put package.json at the ZIP root, with a notyra object alongside normal npm metadata. Unknown notyra fields are ignored. Missing fields, wrong types and invalid values produce errors containing the field and value.

FieldTypeRequiredApplies to / rules
namestringYesBoth. Unscoped npm name, lowercase alphanumeric first character, at most 214 characters. Keep the ID stable after installation
versionstringYesBoth. Semver without a v prefix or surrounding whitespace
descriptionstringNoBoth. Plugin description
authorstring or objectNoBoth. An object contains name: string and optional email: string, url: string
notyra.displayNamestringYesBoth. Nonempty display name
notyra.typefeature or themeYesPlugin kind
notyra.notyraVersionstringYesBoth. node-semver compatibility range, evaluated with prereleases included
notyra.mainstringFeature onlyRequired ESM .js / .mjs path; forbidden for themes
notyra.permissionsarrayFeature onlyRequired array of { name, purpose? }. Empty is valid; duplicates are forbidden. Forbidden for themes
notyra.networkDestinationsstring[]ConditionalFeature. At least one destination is required with network; see networking
notyra.settingsarrayNoFeature. Setting declarations below
notyra.themestringTheme onlyRequired theme .json path
notyra.themeCssstringNoTheme. Extra .css applied only when selected

File paths are relative to the plugin folder. Absolute paths, .., backslashes and colons/drive prefixes are rejected.

Feature example

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Character-count panel",
  "author": { "name": "Developer", "url": "https://example.com" },
  "notyra": {
    "displayName": "My Plugin",
    "type": "feature",
    "notyraVersion": "^3.1.7",
    "main": "dist/index.js",
    "permissions": [],
    "settings": [{ "key": "prefix", "title": "Label", "type": "string", "default": "Characters" }]
  }
}

The template contains a complete runnable implementation.

Settings

Every declaration has a unique key, a display title, a type, a matching default, and optionally a description. A select also requires options: { value: string, label: string }[]; its default must be one of those values.

TypeAccepted valuesNotes
stringStringsEmpty strings are valid
numberFinite numbersNumeric input strings are converted. Empty input, NaN and Infinity are rejected
booleantrue / falseThe string "true" is invalid
selectDeclared option valuesUndeclared values are rejected

Missing or incorrectly typed stored values fall back to defaults. Plugin-provided names, authors, setting labels and permission purposes are displayed literally, without treating them as translation keys.

Theme example

{
  "name": "notyra-theme-blue",
  "version": "1.0.0",
  "notyra": {
    "displayName": "Blue Theme",
    "type": "theme",
    "notyraVersion": "^3.1.7",
    "theme": "theme.json",
    "themeCss": "theme.css"
  }
}

See the theme format for theme.json. IDs must not duplicate builtin themes, custom themes or earlier plugin themes. Theme plugins execute no JavaScript. A complete package is available in official theme plugins.