Plugins

Introduction¶

A Wezterm plugin is a package of Lua files that provide some some predefined functionality not in the core product.

A plugin is distributed via a Git URL.

Tip

Michael Brusegard maintains a list of plugins

Installing a Plugin¶

Brief example:

local wezterm = require 'wezterm'
local a_plugin = wezterm.plugin.require 'https://github.com/owner/repo'

local config = wezterm.config_builder()

a_plugin.apply_to_config(config)

return config

The plugin URL must use the HTTPS or file protocol.

When Wezterm clones the repo into the runtime directory the default branch (probably main) is checked out and used as the plugin source.

Plugins can be configured, for example:

local wezterm = require 'wezterm'
local a_plugin = wezterm.plugin.require 'https://github.com/owner/repo'

local config = wezterm.config_builder()

local myPluginConfig = { enable = true, location = 'right' }

a_plugin.apply_to_config(config, myPluginConfig)

return config

Note

Consult the README for a particular plugin to discover any specific configuration options.

Updating Plugins¶

When changes are published to a plugin repository they are not updated in the local Wezterm instance.

Run the command wezterm.plugin.update_all() to update all local plugins.

Tip

This can be run using the Lua REPL in DebugOverlay.

Removing a Plugin¶

When a plugin is first referenced, wezterm.plugin.require() will clone the repo if it doesn't already exist and store it in the runtime directory under plugins/NAME where NAME is derived from the repo URL.

You can discover locations of the various plugins with wezterm.plugin.list().

To remove the plugin simply delete the appropriate plugin directory.

Developing a Plugin¶

Create a local development repo
Add a file plugin/init.lua
init.lua must return a module that exports an apply_to_config function. This function must accept at least a config builder parameter, but may pass other parameters, or a Lua table with a config field that maps to a config build parameter
Add any other Lua code needed to fulfil the plugin feature set.

Add the plugin using a local file url e.g.

local a_plugin = wezterm.plugin.require "file:///home/user/projects/myPlugin"

Info

When changes are made to the local project, wezterm.plugin.update_all() must be run to sync the changes into the Wezterm runtime directory for testing and use.

Info

This assumes development on the repo default branch (i.e. main). To use a different development branch see below.

Managing a Plugin with Multiple Lua Modules¶

When requiring other Lua modules in your plugin the value of package.path needs to updated with the location of the plugin. The plugin directory can be obtained by running wezterm.plugin.list(). This function returns an array of triplets. e.g.

[
    {
        "component": "filesCssZssZssZsUserssZsdevelopersZsprojectssZsmysDsPlugin",
        "plugin_dir": "/Users/alec/Library/Application Support/wezterm/plugins/filesCssZssZssZsUserssZsalecsZsprojectssZsbarsDswezterm",
        "url": "file:///Users/developer/projects/my.Plugin",
    },
]

The package path can then be updated with the value of plugin_dir. For example:

function findPluginPackagePath(myProject)
  local separator = package.config:sub(1, 1) == '\\' and '\\' or '/'
  for _, v in ipairs(wezterm.plugin.list()) do
    if v.url == myProject then
      return v.plugin_dir .. separator .. 'plugin' .. separator .. '?.lua'
    end
  end
  --- #TODO Add error fail here
end

package.path = package.path
  .. ';'
  .. findPluginPackagePath 'file:///Users/developer/projects/my.Plugin'

Tip

Review other published plugins to discover more details on how to structure a plugin project

Making changes to a Existing Plugin¶

Remove the original plugin from Wezterm
Fork the plugin repo
Clone the repo to a local directory
Optionally set an upstream remote to the original plugin repo. This makes it easier it merge upstream changes
Create a new branch for development
Make the new branch the default branch with git symbolic-ref HEAD refs/heads/mybranch
Set the plugin_dir if required (some plugins hard code the value of the plugin directory).
Add the plugin to Wezterm using the file protocol

Proceed using the develop workflow above