Plugin development

A tessoa plugin is a small program that runs in a sandbox, written in TypeScript or Rust. A plugin can add commands to the context menu, provide the content of a whole page, add columns to the file list and put its own options in Settings. This page shows how to develop, test and package a plugin with the official template. Before you start, have a command line and Git ready on your computer.

Note

The plugin platform on this page needs tessoa 0.29.0 or later. Creating, testing and packaging a plugin do not need tessoa installed; installing the plugin into tessoa to try it out needs version 0.29.0 or later. The plugins on this page are different from preview plugins, which tessoa provides itself for previewing formats such as video and Office documents.

Plugin capabilities

A plugin provides one or more of the capabilities below, each declared in the plugin's manifest, plugin.toml.

Capability	Description
Commands	Appear in the context menu and act on the selected files, for example renaming photos after their capture date
Pages	A whole tab or a section of the sidebar, such as a calculator or a task board. The plugin describes the content and tessoa draws it in its own style
Columns	A column added to the file list, which the user can show from the column menu
Settings	The plugin's own options, shown in tessoa's settings and stored by tessoa
Tasks	Long work that runs in the background, shows its progress and can be cancelled

The sandbox and permissions

A plugin runs in a WebAssembly sandbox in a separate process. It never sees file paths and cannot read or write the disk, reach the network or start programs on its own: the files the user selected reach the plugin as handles, and when the plugin wants to change a file it asks tessoa to do so. Those changes can be undone and are recorded in Activity.

What a plugin may do falls into three levels:

Level	How it is granted	Includes
Automatic	Nothing to declare	Logging, notifications, dialogs, the name, size and other details of the selected files, the plugin's own storage, pages, settings, tasks
Declared	Listed under [permissions] in plugin.toml and shown to the user at installation	Reading the files handed to the plugin, renaming the selected files, writing to the clipboard, connecting to the websites the manifest lists, and more
Consented	Declared, then confirmed by the user inside tessoa	Reserved for later versions: reading a whole folder, changing the content of existing files

Declare only the permissions the plugin really uses. The full list of permission names is in sdk/docs/guide/permissions.md in the template.

Set up the development environment

1. Open tessoa-plugin-template, click Use this template to create your own repository, then clone it.
2. Run the setup script in the repository. It installs only what is missing: Node.js for TypeScript or Rust for Rust, and the tessoa-plugin command-line tool for both.

System	Command
Windows	powershell -ExecutionPolicy Bypass -File scripts/setup.ps1 -Lang ts
macOS, Linux	bash scripts/setup.sh --lang ts

To write the plugin in Rust, replace ts with rust. The script installs for the current user only and needs no administrator rights.

Create the plugin project

1. Run tessoa-plugin init --lang ts --id com.example.my-plugin --name "My plugin". It moves the skeleton of the chosen language to the repository root, fills in the plugin id and name, and deletes the other language's skeleton.
2. Run tessoa-plugin doctor to check that the tools are in place. Fix anything marked FAIL before going on.

The plugin id is globally unique and written in reverse-domain form. It may contain only lower-case letters, digits, ., _ and -.

Write the plugin

A plugin has two parts: the manifest plugin.toml declares what the plugin provides and which permissions it needs, and src/ holds the code. The manifest below declares a context-menu command that appears only for selected images and needs permission to read and rename the selected files:

[plugin]
id = "com.example.rename-by-date"
name = "Rename by capture date"
version = "0.1.0"
api = "tessoa:plugin@0.2.0"
min-host = "0.29.0"

[entry]
kind = "wasm"
file = "dist/plugin.wasm"

[[commands]]
id = "rename-by-date"
title = "Rename by capture date"
where = ["context-menu"]
when = { ext = ["jpg", "jpeg", "heic", "png"], min-selected = 1 }

[permissions]
files = ["read-selected", "rename-selected"]

The template's examples/ folder holds several complete plugins, each with its own tests, for reference. Every manifest key is described in sdk/docs/guide/manifest.md, and the API reference is in sdk/docs/api/.

Tip

The template is organised around how coding assistants work: AGENTS.md at the repository root sends the assistant to the manual in sdk/. Open the repository with a coding assistant and describe the plugin in one sentence, for example "a context-menu command that renames the selected photos after their capture date", and it can create, write, test and package the plugin.

Test and package

Test scenarios go in tests/scenarios/*.toml and the files they use in tests/fixtures/. tessoa-plugin test runs the plugin in the real sandbox against a simulated tessoa, so testing does not need tessoa installed.

Command	What it does
tessoa-plugin test	Builds the plugin and runs every test scenario
tessoa-plugin run	Runs one command on the files you name. The files are really changed
tessoa-plugin check	Checks the manifest and audits the interfaces the build uses
tessoa-plugin package	Writes dist/<id>-<version>.zip and refuses a plugin that fails the audit
tessoa-plugin upgrade	Updates the command-line tool and sdk/, checking signatures and checksums before downloading

Try the plugin in tessoa

1. Start tessoa 0.29.0 or later.
2. Run tessoa-plugin install in the plugin project. It builds and audits the plugin, then hands the project folder to the running tessoa.
3. The first time, tessoa lists the permissions the plugin asks for in its own window; the plugin takes effect once you confirm. After that, tessoa reloads the plugin after every build.

Installing a plugin into tessoa needs a valid licence; creating, testing and packaging do not.

Publish a plugin

Publishing plugins in the plugin community is being prepared. Until then, you can share the packaged ZIP and the source in your own GitHub repository. The skeletons and examples in the template are released under the MIT licence, so a plugin made from them can be used, changed, published and sold freely; sdk/ has its own licence, in sdk/LICENSE.md.

See also

Plugin community · Plugin template · Preview plugins · Activity