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

The core source files of fff.nvim are organized in lua/fff/ and consist of conf.lua for configuration management, core.lua for Rust backend initialization, main.lua for the public API, and 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) 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) 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) 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) 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 – Core file-picker logic for scoring and ranking results
• preview.lua – On-the-fly preview rendering with text, image, and binary detection
• image.lua – Image preview handling via ImageMagick integration
• 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) 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 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), 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) 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 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

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

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

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

Programmatic Search Access

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 lines 84-98).

Summary

• lua/fff/conf.lua – Central configuration management with deprecation handling and default values
• lua/fff/core.lua – Initializes the Rust fff.fuzzy module, creates SQLite databases, and registers global autocommands via ensure_initialized()
• lua/fff/main.lua – Public API exposing setup, find_files, live_grep, and search functions
• 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 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 for text content and image.lua for image rendering via ImageMagick. These modules activate when preview.enabled is true in the configuration and integrate with 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 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. The 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}