# Core Source Files of fff.nvim: Architecture and Implementation Guide

> Explore the core source files of fff.nvim in lua/fff/. Understand configuration, Rust backend, public API, and UI rendering for efficient Neovim file management.

- Repository: [Dmitriy Kovalenko/fff.nvim](https://github.com/dmtrKovalenko/fff.nvim)
- Tags: architecture
- Published: 2026-04-04

---

**The core source files of fff.nvim are organized in `lua/fff/` and consist of [`conf.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/conf.lua) for configuration management, [`core.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/core.lua) for Rust backend initialization, [`main.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/main.lua) for the public API, and [`picker_ui.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/picker_ui.lua) for UI rendering, all orchestrating the Rust `fff.fuzzy` module for high-performance fuzzy matching.**

fff.nvim is a fast, feature-rich file finder for Neovim powered by a Rust backend. Understanding the core source files of fff.nvim helps developers customize the plugin and debug its Lua-based orchestration layer. The codebase follows a strict separation where `lua/fff/*.lua` handles configuration and UI, while the heavy computation occurs in the compiled `fff.fuzzy` Rust module.

## Configuration Management in conf.lua

The [[`lua/fff/conf.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/conf.lua)](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/conf.lua) file serves as the central configuration system. It manages user settings, applies deprecation migrations, and provides sensible defaults through the `M.get()` function.

Every component receives its settings via `M.get()`, which returns a fully merged configuration table. When you call `require('fff').setup(opts)`, the options are stored in `vim.g.fff` and merged with defaults automatically.

## Initialization and Core Engine (core.lua)

The [[`lua/fff/core.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/core.lua)](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/core.lua) module is responsible for bootstrapping the Rust fuzzy engine. The critical function `ensure_initialized()` performs several key operations:

- Loads the Rust module via `require('fff.fuzzy')`
- Initializes SQLite databases for frecency scoring and history tracking
- Calls `fuzzy.init_file_picker` with the configured `base_path`
- Registers global autocommands for tracking file accesses (`BufEnter`) and reacting to directory changes (`DirChanged`)

This file acts as the bridge between Lua and Rust, ensuring the backend is ready before any API functions execute.

## Public API Entry Points (main.lua)

The [[`lua/fff/main.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/main.lua)](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/main.lua) file exposes the high-level user-facing functions. Key exports include:

- **`setup(config)`** – Stores configuration in `vim.g.fff`
- **`find_files(opts)`** – Opens the file picker UI
- **`live_grep(opts)`** – Initiates search within file contents
- **`search(query, limit)`** – Programmatic fuzzy search returning Lua tables
- **`open_file_under_cursor()`** – Opens files matching the text under the cursor

Each API function internally calls `core.ensure_initialized()` before forwarding options to the UI layer.

## UI Rendering and Picker Logic (picker_ui.lua)

The [[`lua/fff/picker_ui.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/picker_ui.lua)](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/picker_ui.lua) module handles all visual presentation. It manages floating window creation, layout calculations, and input handling.

When `find_files()` or `live_grep()` is invoked, `picker_ui` receives the configuration and queries the Rust backend for results. It then dispatches to appropriate renderers based on the content type, handling user interactions like scrolling and selection entirely within Lua.

## File Picker Subsystem (file_picker/)

The `lua/fff/file_picker/` directory contains specialized modules for file presentation:

- **[`init.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/init.lua)** – Core file-picker logic for scoring and ranking results
- **[`preview.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/preview.lua)** – On-the-fly preview rendering with text, image, and binary detection
- **[`image.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/image.lua)** – Image preview handling via ImageMagick integration
- **[`icons.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/icons.lua)** – File type icon mapping and Git status symbol decoration

These modules activate when `preview.enabled` is true in the configuration, providing rich file inspection without leaving the picker interface.

## Grep and Search Rendering (grep_renderer.lua)

For live grep functionality, [[`lua/fff/grep/grep_renderer.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/grep/grep_renderer.lua)](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/grep/grep_renderer.lua) formats search results with line numbers and match highlighting. The `grep` table passed to `live_grep()` merges with global configuration (as seen in [`main.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/main.lua) lines 30-38) to control case sensitivity and display options.

## Git Integration and Utilities (git_utils.lua, utils/)

Git status decoration occurs through [[`lua/fff/git_utils.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/git_utils.lua)](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/git_utils.lua), which queries repository status and defines highlight groups. Utility functions for filesystem operations reside in [[`lua/fff/utils/fs.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/utils/fs.lua)](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/utils/fs.lua) and companion modules, providing cross-platform compatibility helpers used throughout the codebase.

## Rust Backend Bridge (fff.fuzzy)

The actual fuzzy matching, indexing, frecency scoring, and grep operations occur in the Rust `fff.fuzzy` module. Loaded in [`core.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/core.lua) via `require('fff.fuzzy')`, this compiled extension handles all performance-critical text processing while Lua manages the orchestration and display layers.

## Practical Implementation Examples

### Basic Setup Configuration

```lua
require('fff').setup({
  base_path = vim.fn.getcwd(),
  preview = { enabled = true },
  keymaps = {
    close = 'q',
    select = '<CR>',
    move_up = { 'k', '<Up>' },
    move_down = { 'j', '<Down>' },
  },
})

```

### File Finder Keymap

```lua
vim.keymap.set('n', '<leader>f', function()
  require('fff').find_files()
end)

```

*Behind the scenes, this triggers `core.ensure_initialized()` before launching `picker_ui`.*

### Live Grep with Overrides

```lua
vim.keymap.set('n', '<leader>g', function()
  require('fff').live_grep({
    title = '🔎 Search Project',
    grep = { smart_case = false },
  })
end)

```

### Programmatic Search Access

```lua
local results = require('fff').search('init.lua', 10)
for _, item in ipairs(results) do
  print(item.relative_path, item.frecency_score)
end

```

This calls `fuzzy.fuzzy_search_files` with threading and pagination parameters (see [`main.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/main.lua) lines 84-98).

## Summary

- **[`lua/fff/conf.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/conf.lua)** – Central configuration management with deprecation handling and default values
- **[`lua/fff/core.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/core.lua)** – Initializes the Rust `fff.fuzzy` module, creates SQLite databases, and registers global autocommands via `ensure_initialized()`
- **[`lua/fff/main.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/main.lua)** – Public API exposing `setup`, `find_files`, `live_grep`, and `search` functions
- **[`lua/fff/picker_ui.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/picker_ui.lua)** – Manages floating window UI, layout calculations, and result display
- **`lua/fff/file_picker/`** – Submodule providing file previews, image rendering, and iconography
- **`fff.fuzzy`** – Rust backend handling all fuzzy matching, indexing, and grep operations

## Frequently Asked Questions

### What is the role of core.lua in fff.nvim?

The [`core.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/core.lua) file acts as the initialization gateway for the entire plugin. It exposes `ensure_initialized()`, which loads the Rust `fff.fuzzy` module, creates necessary SQLite databases for frecency tracking, and registers autocommands for monitoring file access and directory changes.

### How does fff.nvim handle file previews?

File previews are managed by the `lua/fff/file_picker/` submodule, specifically [`preview.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/preview.lua) for text content and [`image.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/image.lua) for image rendering via ImageMagick. These modules activate when `preview.enabled` is true in the configuration and integrate with [`picker_ui.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/picker_ui.lua) to display content in the picker window.

### Where is the actual fuzzy matching logic implemented?

The fuzzy matching logic resides in the Rust `fff.fuzzy` module, not in Lua. This compiled backend is loaded via `require('fff.fuzzy')` in [`core.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/core.lua) and handles all indexing, scoring, and searching operations while Lua manages the UI and configuration layers.

### How do I customize the default configuration?

Modify the table passed to `require('fff').setup()` in your [`init.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/init.lua). The [`conf.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/conf.lua) module merges your settings with defaults and stores the result in `vim.g.fff`, making custom keymaps, preview settings, and grep options available to all plugin components.