telescope-alternate.nvim
A Neovim plugin to quickly navigate between related files using regex patterns, with support for Telescope and fzf-lua.
What is telescope-alternate.nvim?
telescope-alternate is a Neovim plugin that allows developers to quickly jump between related files in a project using user-defined regex patterns. It solves the problem of tedious manual navigation between files like tests and implementations or services and contracts by mapping these relationships once.
Neovim users working on structured projects (e.g., Rails, NestJS, Angular) who frequently switch between related files and want to optimize their workflow.
It offers a flexible, pattern-driven approach to file navigation with support for multiple pickers (Telescope/fzf-lua), automatic file creation, and pre-built presets, reducing friction in large codebases.
Overview
Alternate between common files using pre-defined regexp. Just map the patterns and starting navigating between files that are related.
Use Cases
Best For
- Switching between Ruby on Rails models and their corresponding tests or controllers
- Navigating between NestJS modules and their services or controllers
- Jumping from Angular components to their templates or styles
- Linking custom file relationships in monorepos or structured applications
- Quickly accessing related files without remembering exact paths
- Creating missing related files on the fly during development
Not Ideal For
- Projects with highly dynamic or non-standard file structures that don't follow consistent naming conventions
- Developers who prefer zero-configuration tools and rely solely on language servers or built-in editor navigation
- Teams not using Telescope or fzf-lua, as the plugin depends on one of these pickers to function
Pros & Cons
Pros
Allows custom regex patterns to define any file relationship, such as linking Rails models to tests or NestJS modules to services, enabling tailored navigation for complex codebases.
Supports both Telescope and fzf-lua as selection interfaces, giving users choice and flexibility, as highlighted in the configuration options and installation notes.
Can create missing destination files on the fly, including those with regex placeholders, which streamlines development when adding new related files, as demonstrated in the demo and mappings.
Includes ready-made mappings for Rails, RSpec, NestJS, and Angular, reducing setup time for common project structures, as listed in the presets section.
Cons
Setting up custom regex mappings requires detailed Lua patterns, which can be error-prone and time-consuming, especially for users unfamiliar with regex or the plugin's syntax, as seen in the lengthy configuration examples.
Relies on Telescope or fzf-lua being installed and configured, adding to plugin bloat and setup complexity, and it does not work with other pickers or vanilla Neovim out of the box.
Less effective for projects without clear file naming or directory patterns, as the regex-based approach assumes consistency, making it cumbersome for ad-hoc or legacy codebases.
Frequently Asked Questions
Related Projects
workspaces.nvima simple plugin to manage workspace directories in neovim
projections.nvimA map to your filesystem. A Neovim plugin for fast session switching and project discovery.
telescope-repo.nvim🦘 Jump into the repositories (git, mercurial…) of your filesystem with telescope.nvim, without any setup
project.nvimActively maintained fork of ahmedkhalf/project.nvim. Detects and chdirs to the project root, with its own UI, provides lualine component, supports oil.nvim, includes pickers for telescope, snacks, fzf-lua, and picker.nvim.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.