Writing Plugins

Anyone who can write Lua code, can write xplr plugins.

Just follow the instructions and best practices:

Naming

xplr plugins are named using hiphen (-) separated words that may also include integers. They will be plugged using the require() function in Lua.

Structure

A minimal plugin should confirm to the following structure:

.
├── README.md
└── init.lua

You can also use this template.

README.md

This is where you document what the plugin does, how to use it, etc.

init.lua

This file is executed to load the plugin. It should expose a setup() function, which will be used by the users to setup the plugin.

Example:

local function setup(args)
  local xplr = xplr
  -- do stuff with xplr
end

return { setup = setup }

Publishing

When publishing plugins on GitHub or other repositories, it's a best practice to append .xplr to the name to make them distinguishable. Similar to the *.nvim naming convention for Neovim plugins.

Finally, after publishing, don't hesitate to let us know.

Best practices

  • Try not to execute a lot of commands at startup, it may make xplr slow to start.
  • When executing commands, prefer Call0 over Call, BashExec0 over BashExec and so on. File names may contain newline characters (e.g. foo$'\n'bar).
  • File names may also contain quotes. Avoid writing directly to $XPLR_PIPE_MSG_IN. Use xplr -m / xplr --pipe-msg-in instead.
  • Check for empty variables using the syntax ${FOO:?} or use a default value ${FOO:-defaultvalue}.

Examples

Visit Awesome Plugins for xplr plugin examples.

Also See