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 describe the desktop 2.34.0 source contract and Plugin API 2.1. 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
Theme and icon assets	Special asset paths with current host restrictions; see 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

The host recognizes type: "icon-theme" with an iconsPath directory of SVG assets. This does not expose a general worker API for changing icons or host CSS. Check discovery and filename mapping in the intended Zync version, and confirm registry support with maintainers before distributing a new asset-only format.

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.