Plugin API Overview

Overview of Yazi’s Lua Plugin API for extending functionality

Introduction

Yazi provides a powerful Lua plugin API that allows you to extend and customize its functionality. Plugins can be used for:

• Custom file previewers
• File operations and automation
• UI components and themes
• Integration with external tools
• Custom actions and keybindings

Lua Version

Yazi uses Lua 5.5 as of version 0.4.0 (upgraded from Lua 5.4). This upgrade brings performance improvements through external strings, reducing memory allocations.

Lua 5.5 introduces external strings for better memory efficiency. See #3633 for details.

API Namespaces

The plugin API is organized into several global namespaces:

Core APIs

• ya - Core Yazi API for async operations, sync blocks, logging, and utilities
• fs - Filesystem operations (copy, rename, read_dir, etc.)
• ui - UI rendering components and helpers
• ps - Publish/Subscribe messaging system
• cx - Context API for accessing application state

Configuration APIs

• rt - Runtime configuration (args, mgr, preview, tasks, etc.)
• th - Theme colors and styling

Async Support

Yazi’s plugin system supports asynchronous operations through Lua coroutines:

Module-level Async

Plugins can use the @sync annotation to declare async entry points:

--- @sync peek
local M = {}

function M:peek(job)
  -- This function runs in sync context
  -- Can call async APIs directly
  local cha, err = fs.cha(job.file.url)
end

return M

Runtime Async

For dynamic async operations, use ya.async():

local handle = ya.async(function()
  -- Async code here
  local files = fs.read_dir(Url("/path"), { limit = 100 })
end)

Sync Blocks

Use ya.sync() to execute code in the main thread with access to the plugin context:

local config = ya.sync(function()
  return plugin.config
end)

Plugin Types

Yazi supports several types of plugins:

Previewers

Generate file previews for the preview pane:

function M:peek(job)
  local cha = fs.cha(job.file.url)
  if not cha then
    return
  end
  
  ya.preview_widget(job, ui.Text("Preview content"):area(job.area))
end

Preloaders

Load file metadata in the background:

function M:preload(job)
  local cache = ya.file_cache(job)
  if cache then
    return 1  -- Already cached
  end
  
  -- Load and cache data
  return 2  -- Fully loaded
end

Actions

Custom user actions triggered by keybindings:

function entry()
  local h = cx.active.current.hovered
  if h then
    ya.manager_emit("open", { h.url })
  end
end

Init Plugins

Run on startup from init.lua:

-- ~/.config/yazi/init.lua
require("custom-plugin"):setup()

Error Handling

Most async APIs return (result, error) tuples:

local cha, err = fs.cha(url)
if not cha then
  ya.err("Failed to get metadata: " .. tostring(err))
  return
end

Create custom errors:

local err = Error.custom("Something went wrong")
return nil, err

Data Types

Common userdata types:

• Url - File/directory URL (local or remote)
• Path - Local filesystem path
• File - File metadata and attributes
• Cha - File characteristics (size, permissions, etc.)
• Rect - Screen rectangle (x, y, w, h)
• Id - Unique identifier

Best Practices

1. Use async APIs - Most filesystem operations are async for better performance
2. Handle errors - Always check error returns from async functions
3. Cache data - Use ya.file_cache() for expensive operations
4. Limit resources - Use options like limit in fs.read_dir() to avoid loading too much data
5. Clean up - Drop file descriptors and handles when done using ya.drop()

Next Steps

• Global Functions - Global utility functions
• Filesystem API - File operations
• UI API - Rendering components
• Context API - Application state
• Yazi API - Core utilities
• PubSub API - Messaging system