Plugins

Introduction

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

A plugin is distributed via a Git URL.

!!! Tip

Michael Brusegard maintains a [list of plugins](https://github.com/michaelbrusegard/awesome-wezterm)

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](../troubleshooting.md#debug-overlay).

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

1. Create a local development repo
2. Add a file plugin/init.lua
3. 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
4. Add any other Lua code needed to fulfil the plugin feature set.
5. Add the plugin using a local file url e.g.
   luaCopy

   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

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

Proceed using the develop workflow above