Phials developer documentation
User guide
AI Notice: Most documentation right now was auto-generated by an LLM. Handwritten documentation will be implemented over time on the road to 1.0

Community plugins

Community plugins are packaged as JavaScript bundles containing a manifest.json, a main.js file, and an optional styles.css file. Phials installs these files in its data directory, manages updates using a community registry and GitHub releases, and imports main.js at runtime. Your plugin’s entry point must export a default function that returns a PhialsPlugin.

Phials wraps the PluginAPI with permission checks derived from your plugin’s manifest. This gates access to capabilities like file system access, clipboard actions, and network requests. Because community plugins execute directly in the application’s renderer process, they are trusted code and do not run in a secure sandbox. Refer to the Public API contract for more details.

See also: Plugin API and lifecycle and Getting started.

Community plugins safe mode

By default, Phials enables safe mode for new user profiles. When safe mode is active:

  • You cannot install, enable, or update community plugins.
  • Any community plugins that were previously enabled are temporarily disabled.

To install or run community plugins, users must go to Settings > Plugins > Community plugins, toggle off safe mode, and accept the security warning. Shipped features are unaffected by safe mode.

Manifest schema

The plugin manifest is defined in your project’s manifest.json. You can find manifest parsing and validation helpers in the example repository under sdk/manifest-schema.ts.

Required fields:

  • id: A reverse-DNS string matching ^[a-z][a-z0-9]*\.[a-z][a-z0-9-]*[a-z0-9]$ (for example, com.example.my-plugin). The phials.* namespace is reserved.
  • name: The user-facing name of your plugin.
  • version: The semver version of your plugin.
  • minAppVersion: The minimum Phials version required.
  • author: Your name or organization.
  • description: A brief description of the plugin.

Optional fields:

  • authorUrl: A link to your website.
  • repository: A link to the source code repository.
  • icons: Iconify identifiers for plugin settings pages.
  • permissions: An array of permissions.
  • pluginApiVersion: The version of the plugin API contract (defaults to 1.0.0).

Requested permissions must be a subset of the following:

  • filesystem.read
  • filesystem.write
  • clipboard.read
  • clipboard.write
  • network.fetch

Note that the shell.execute permission is not supported in the current version.

Minimal manifest example:

{
  "id": "com.example.hello-plugin",
  "name": "Hello Plugin",
  "version": "1.0.0",
  "minAppVersion": "0.1.0",
  "pluginApiVersion": "1.0.0",
  "author": "You",
  "description": "Example external plugin bundle.",
  "permissions": ["filesystem.read", "network.fetch"]
}

Compatibility

During installation and startup, Phials checks compatibility:

  • minAppVersion is validated against the running Phials application version.
  • pluginApiVersion (defaulting to 1.0.0) is validated against the API version supported by the application.

Both requirements must be met before the plugin can activate. See Public API contract for versioning rules.

Plugin lifecycle states

Initialization

During startup, Phials reads all installed plugin manifests, checks if safe mode is enabled, and activates all enabled plugins.

Installation

When installing a plugin from the community registry, Phials downloads the manifest.json, main.js, and optional styles.css files. It validates the plugin ID, compatibility, and permission declarations before saving the files. New plugins remain disabled until you manually enable them in settings.

Activation and deactivation

Enabling a plugin triggers its activation. Phials imports the plugin bundle, registers its providers, and runs its onActivate hook. Disabling a plugin removes its providers, tears down event listeners, and unloads any injected stylesheets.

Updates

When a plugin is updated, Phials replaces its files with the new version. If the updated plugin requires new permissions, you must review and approve them before the plugin can activate. If activation fails during an update, Phials rolls back to the previous version.

Permission-gated API features

Tauri commands (invoke)

The Tauri command names you can call via api.invoke depend on the permissions in your manifest. Phials permits a baseline of always-allowed commands, including system paths, drive listings, thumbnails, and platform probes. The filesystem.read permission enables reading files and directory listings, while filesystem.write enables writing and modifying files. Attempting to invoke any other command throws a permission error.

Clipboard

The clipboard.read and clipboard.write permissions enable the corresponding helper methods on api.clipboard.

Network requests

The network.fetch permission enables the api.fetch helper. Note that because plugins run in the renderer process, this permission does not block native browser APIs like global fetch calls. See the Public API contract for more details.

Trust model

Phials relies on GitHub release assets and pull request reviews in the community registry. It does not require cryptographic signatures or checksum validations.

Submitting to the community registry

The community registry is managed in the github.com/EliWimmer/phials-plugins repository. To submit your plugin, read the SUBMISSION.md checklist. For details on policy, takedowns, and ownership, see POLICY.md.

Current limitations

  • Plugins are distributed exclusively through GitHub Releases and the community index.
  • Plugins run in the same renderer process as Phials. Stronger process-level isolation is not supported. See the Public API contract for security details.