Plugins and Extensions

Zync plugins add focused commands, workspace panes, and editor integrations. New community plugins should use Manifest v2 and the published Zync SDK. These guides include the desktop 2.36.0 data-only icon-pack contract in Plugin API 2.2. The worker examples retain their stated SDK and API requirements; an icon-pack contribution does not add new worker methods. Test your package against the earliest installed Zync version you claim to support.

Install and manage plugins

Open Settings > Plugins > Marketplace. Review the publisher, version, source, and required and optional permissions before approving installation. The desktop verifies signed registry metadata and package integrity before activation.

Under Installed, inspect a plugin, change optional permissions, disable it, or uninstall it. Uninstall keeps private plugin data by default; Uninstall and delete data removes it. Follow any restart notice shown by Zync. When a retained previous version is available, the plugin details offer rollback.

Signatures establish provenance

A valid signature identifies the signing key and protects package integrity. It does not establish that the plugin’s behavior is safe. SSH command permissions allow work with the connected account’s authority, even when Zync never exposes the account’s password or private key to the plugin.

Build a community plugin

Follow these guides in order:

1. Build your first plugin: starter, manifest, local installation, and debugging.
2. Plugin API and permissions: supported worker and pane APIs, compatibility, and limits.
3. Sign and publish a plugin: keys, signed ZIPs, checksums, registry review, and updates.
4. Plugin best practices: architecture, server safety, UI, performance, and release testing.

The SDK and optional UI primitives are separate MIT packages. Installing either npm package does not publish your plugin to Zync’s Marketplace.

Extension types

Extension	Current authoring path
Commands and background logic	Manifest v2 worker with declared commands and brokered permissions
Workspace pane	Manifest v2 contributes.paneKinds plus packaged HTML, CSS, and JavaScript
Dashboard card	Manifest schema recognizes declarations; the public worker SDK has no dashboard registration API yet
Editor provider	Separate editor manifest fields and zyncEditor document bridge; use Zedit as a reference
File icon pack	Data-only Manifest v2 iconTheme contribution; Plugin API 2.2+
Color theme assets	Host CSS restrictions apply; see Theme plugins below

Workers have no DOM, Node.js APIs, or runtime npm module loader. Panes have their own DOM in an isolated iframe and communicate with their worker through Zync. The worker calls permitted host APIs. A pane does not inherit the worker API.

Permissions and side effects

Manifest v2 uses named permissions with explanations, not the old array of broad strings such as "terminal" or "panel". Installation approval is bound to the package being reviewed. Required permissions are necessary for installation; optional permissions may be declined or revoked.

Permission names alone do not promise an implemented API. Use the supported operations in the API guide. In particular, do not copy legacy examples using zync.fs, zync.window.create, zync.terminal.send, zync.theme.set, or raw window.zync.ssh.exec into a Manifest v2 plugin.

Panel plugins

A v2 worker registers a declared pane ID using zync.panel.register(id). Its HTML comes from the manifest’s packaged entry file. Do not pass HTML strings to the old panel.register(id, title, html) API. See the working starter.

Editor provider contract

Editor frames receive window.zyncEditor, a separate bridge for document events, changes, dirty state, save requests, and cursor status. The host performs the file save. Inspect the current Zedit source and the SDK’s @zync-sh/plugin-sdk/editor types before implementing a provider. See editor compatibility for the current manifest and lifecycle constraints.

Icon theme contract

In Zync 2.36.0, new external packs use Manifest v2, type: "icon-theme" and a versioned iconTheme object. They contain data and static SVG assets only, not a worker, pane, stylesheet or permission request. Require a Plugin API range whose minimum is 2.2.0; do not advertise compatibility with API 2.1 hosts.

manifest.json

{
  "manifestVersion": 2,
  "id": "dev.example.icons",
  "publisher": "dev.example",
  "name": "Example Icons",
  "version": "1.0.0",
  "license": "MIT",
  "engines": {
    "zync": ">=2.36.0",
    "pluginApi": ">=2.2.0, <3.0.0"
  },
  "type": "icon-theme",
  "iconTheme": {
    "version": 1,
    "iconDefinitions": {
      "file": { "iconPath": "icons/file.svg" },
      "folder": { "iconPath": "icons/folder.svg" },
      "code": { "iconPath": "icons/code.svg" }
    },
    "file": "file",
    "folder": "folder",
    "fileNames": { "package.json": "code" },
    "fileExtensions": { "ts": "code", "tar.gz": "file" },
    "folderNames": { "src": "code" }
  }
}

Include the three referenced SVG files in the package. The publisher must match your registered identity, and every mapping value must name an entry in iconDefinitions. file and folder are required fallback icon IDs. Exact file names take priority over extension mappings; the longest compound extension wins. Name and extension associations are case-insensitive and do not change filesystem path identity.

The host limits a pack to 512 definitions and 2,048 total associations, with each SVG at most 128 KiB. Assets must be regular package-local .svg files, with no symlinks, path traversal or remote URLs. Static SVG validation rejects executable content, external resources and unsupported markup. Do not add main, runtime, style, editor, iconsPath, executable contributions or nonempty permissions to a declarative pack.

Enabled packs appear in Settings > Plugins > Installed > Select Icon Set. Built-in identities cannot be replaced by an external package. Existing legacy iconsPath discovery remains a compatibility path, not a reason to omit the new mapping schema.

Use the same signed-package review and registry process described in Sign and publish a plugin. Confirm that the SDK and registry tooling used for publication accepts this data-only format; successful local installation does not prove marketplace acceptance.

Theme plugins

Only app-owned built-in theme styles are injected into the host document. Third-party pane and editor styles stay inside their iframe. A legacy manifest with style: "theme.css" is not a supported way to restyle the whole app through the signed v2 marketplace. Use Themes for the current boundary and the UI package to make your own pane follow Zync’s theme.

Packaging and installing locally

Use Settings > Plugins > Developer, enable Developer Mode, and install your built folder or ZIP. manifest.json must be at its root. Developer Mode permits local and legacy testing; it does not bypass manifest validation or grant all permissions. Turning it off stops local and legacy plugins. Test the signed marketplace path separately before announcing a public release.

Marketplace and registries

The current signed registry lives in zync-plugin-registry. Publishers submit released artifacts and public-key identity for review. Registry operators approve publisher/repository/key bindings and sign the registry separately.

A self-hosted unsigned JSON array is not interchangeable with signed registry metadata; a desktop build’s configured public roots determine which registry it trusts.

Publish to the official marketplace

Follow Sign and publish a plugin. It covers the exact release assets and input files, and separates publisher work from operator work. Do not send private signing keys with a submission.

Plugin notifications

Declare ui.notifications.emit before calling zync.ui.notify. Actionable notifications use JSON action IDs and zync.ui.onNotifyAction, not functions in the payload. Handle failures and keep notification volume low. See Notifications for user preferences and the API guide for the payload contract.