> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sxyazi/yazi/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  Lua 5.5 introduces external strings for better memory efficiency. See [#3633](https://github.com/sxyazi/yazi/pull/3633) for details.
</Note>

## 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:

```lua theme={null}
--- @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()`:

```lua theme={null}
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:

```lua theme={null}
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:

```lua theme={null}
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:

```lua theme={null}
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:

```lua theme={null}
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`:

```lua theme={null}
-- ~/.config/yazi/init.lua
require("custom-plugin"):setup()
```

## Error Handling

Most async APIs return `(result, error)` tuples:

```lua theme={null}
local cha, err = fs.cha(url)
if not cha then
  ya.err("Failed to get metadata: " .. tostring(err))
  return
end
```

Create custom errors:

```lua theme={null}
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](globals) - Global utility functions
* [Filesystem API](fs) - File operations
* [UI API](ui) - Rendering components
* [Context API](cx) - Application state
* [Yazi API](ya) - Core utilities
* [PubSub API](ps) - Messaging system