Firenvim

Turn your browser¹ into a [Neovim][neovim] client (demos: justinmk 🇺🇸, Sean Feng 🇨🇳).

¹ _{Firefox and Chrome are specifically supported. Other Chromium based browsers such as Brave, Vivaldi, Opera, and Arc should also work but are not specifically tested.}

How to use

Just click on any textarea and it will be immediately replaced by an instance of Firenvim. To set the content of the now hidden textarea to the content of the Neovim instance, simply :w. If you want to close the Firenvim overlay and return to the textarea, use :q. If you selected an element where you expected the Firenvim frame to appear and it didn't, try pressing <C-e>.

Installing

Before installing anything please read SECURITY.md and make sure you're okay with everything mentioned. In the event you think of a way to compromise Firenvim, please send me an email (you can find my address on my website).

1. Install Firenvim as a regular [Neovim][neovim] plugin, then run the built-in post-install script.

   • lazy

     ```lua { 'glacambre/firenvim', build = ":call firenvim#install(0)" }

   • vim-plug

     vim Plug 'glacambre/firenvim', { 'do': { _ -> firenvim#install(0) } }

   • minpac

     vim call minpac#add('glacambre/firenvim', { 'type': 'opt', 'do': 'packadd firenvim | call firenvim#install(0)'}) if exists('g:started_by_firenvim') packadd firenvim endif

   • vundle, others

     Install the plugin as you usually would, then run this shell command:

     sh $ nvim --headless "+call firenvim#install(0) | q"

2. Install the Firenvim addon for your browser from Mozilla's store or Google's.

If you would rather build and install Firenvim from source, check CONTRIBUTING.md.

Other browsers

Other browsers aren't supported for now. Opera, Vivaldi and other Chromium-based browsers should however work just like in Chromium and have similar install steps. Brave, Edge, and Arc might work, Safari doesn't (it doesn't support Webextensions).

Permissions

Firenvim currently requires the following permissions for the following reasons:

• Access your data for all websites: this is necessary in order to be able to append elements (= the Neovim iframe) to the DOM.
• Exchange messages with programs other than Firefox: this is necessary in order to be able to start Neovim instances.

Configuring Firenvim

Manually triggering Firenvim

You can configure the keybinding to manually trigger Firenvim (<C-e> by default) in the shortcuts menu in about:addons on Firefox, or in chrome://extensions/shortcuts on Chrome.

Temporarily disabling Firenvim in a tab

Temporarily disabling (and re-enabling) Firenvim in a tab can be done either by clicking on the Firenvim button next to the urlbar or by configuring a browser shortcut (see the previous section to find out how browser shortcuts can be configured).

Building a Firenvim-specific config

Note: If you would prefer VimScript examples, you can consult the (outdated) readme from commit 132979166a02319f0b49815135e60a4e4599de91 or earlier.

New: With Neovim nightly builds from 2023/02/17 or more recent, you can use $NVIM_APPNAME to define a completely separate firenvim config. In order to do that, make sure "NVIM_APPNAME" is appropriately set when you run firenvim#install().

When it starts Neovim, Firenvim sets the variable g:started_by_firenvim which you can check to run different code in your init.lua. For example:

if vim.g.started_by_firenvim == true then
  vim.o.laststatus = 0
else
  vim.o.laststatus = 2
end

Alternatively, you can detect when Firenvim connects to Neovim by using the UIEnter autocmd event:

vim.api.nvim_create_autocmd({'UIEnter'}, {
    callback = function(event)
        local client = vim.api.nvim_get_chan_info(vim.v.event.chan).client
        if client ~= nil and client.name == "Firenvim" then
            vim.o.laststatus = 0
        end
    end
})

Similarly, you can detect when Firenvim disconnects from a Neovim instance with the UILeave autocommand.

Using different settings depending on the url/page/element being edited

The Neovim buffer loaded into a textarea is given a unique name. All buffers are named something like this: domainname_page_selector.txt (see the toFileName function).

This alows you to configure different settings by creating autocommands targeting/matching the buffername for that url/page/element. For example, this will set file type to markdown for all GitHub buffers:

vim.api.nvim_create_autocmd({'BufEnter'}, {
    pattern = "github.com_*.txt",
    command = "set filetype=markdown"
})

To view the buffername of your Neovim instance in a textarea, use :buffers.

Understanding Firenvim's configuration object

You can configure everything else about Firenvim by creating a dictionary named vim.g.firenvim_config in your init.lua and setting the keys "globalSettings" and "localSettings". In the dictionary vim.g.firenvim_config["localSettings"] you can map Javascript patterns that match against the full URL to settings that are used for all URLs matched by that pattern. When multiple patterns match a URL, the pattern with the highest "priority" value is used. Here is an example (the settings and their possible values will be explained in the next subsections):

vim.g.firenvim_config = {
    globalSettings = { alt = "all" },
    localSettings = {
        [".*"] = {
            cmdline  = "neovim",
            content  = "text",
            priority = 0,
            selector = "textarea",
            takeover = "always"
        }
    }
}

With this configuration, takeover will be set to always on all websites. If we wanted to override this value on british websites, we could add the following lines to our init.vim. Notice how the priority of this new regex is higher than that of the .* regex:

vim.g.firenvim_config.localSettings["https?://[^/]+\\.co\\.uk/"] = { takeover = 'never', priority = 1 }

Configuring what elements Firenvim should appear on

The selector attribute of a localSetting controls what elements Firenvim automatically takes over. Here's the default value:

vim.g.firenvim_config.localSettings['.*'] = { selector = 'textarea:not([readonly], [aria-readonly]), div[role="textbox"]' }

If you don't want to use Firenvim with rich text editors (e.g. Gmail, Outlook, Slack…) as a general rule, you might want to restrict Firenvim to simple textareas:

vim.g.firenvim_config.localSettings['.*'] = { selector = 'textarea' }

Since selector is just a CSS selector, you have access to all of CSS's pseudo selectors, including :not(), which allows you to exclude elements that have certain attributes, like this:

vim.g.firenvim_config.localSettings['.*'] = { selector = 'textarea:not([class=xxx])' }

Configuring Firenvim to not always take over elements

Firenvim has a setting named takeover that can be set to always, empty, never, nonempty or once. When set to always, Firenvim will always take over elements for you. When set to empty, Firenvim will only take over empty elements. When set to never, Firenvim will never automatically appear, thus forcing you to use a keyboard shortcut in order to make the Firenvim frame appear. When set to nonempty, Firenvim will only take over elements that aren't empty. When set to once, Firenvim will take over elements the first time you select them, which means that after :q'ing Firenvim, you'll have to use the keyboard shortcut to make it appear again. Here's how to use the takeover setting:

vim.g.firenvim_config.localSettings['.*'] = { takeover = 'always' }

Choosing a command line

You can chose between Neovim's built-in command line, firenvim's command line and no command line at all by setting the localSetting named cmdline to either neovim, firenvim or none, e.g.:

vim.g.firenvim_config.localSettings['.*'] = { cmdline = 'firenvim' }

Choosing none does not make sense unless you have alternative way to display the command line such as noice.nvim.

Editing HTML directly

The content localSetting controls how Firenvim should read the content of an element. Setting it to html will make Firenvim fetch the content of elements as HTML, text will make it use plaintext. The default value is text:

vim.g.firenvim_config.localSettings['.*'] = { content = 'html' }

Special characters on macOS

On macOS, the default keyboard layouts emit special characters when the alt (i.e. option) key is held down. From the perspective of the browser, these special characters replace the underlying "main" character of a keystroke event while retaining the modifier. For example, in the standard US layout the key chord alt-o is received in the browser as alt-ø rather than alt-o. Further, certain alt-chords represent "dead keys", which apply a diacritic to the next character entered. Pressing alt-e followed by a produces the single character "á" while alt-u followed by a produces "ä". To produce this behavior, diacritic-mapped strokes like alt-e and alt-u are themselves mapped to a "Dead key" character.

These behaviors complicate the support of special character and alt/meta (A- or M-) vim mappings on macOS in two ways:

1. There is no way to generate unmodified special character key events. For example, since the only way to generate the character "ø" via the keyboard is by holding down alt, any key event with the "ø" character will also have an alt modifier. If we forward this directly to Vim, it will be received as <M-ø>.

2. There is no way to generate alt-modified plain alphanumeric characters. For example, an <M-o> mapping won't work because pressing alt-o generates <M-ø> rather than <M-o>.

Terminal and standalone GUI applications can solve these problems by changing the interpretation of the alt key at the application level. Terminal.app and iTerm2, for instance, both provide a "use Option as Meta key" preference that converts incoming alt-chords at the application level. Firenvim, however, is a browser extension that operates off of browser keystroke events rather than application-level events. At present, we are unsure how to implement this "use option as meta" functionality at the browser event level (help here is welcome!). However, there are some workarounds.

For problem (1), Firenvim will by default drop the alt key on macOS for any special character, defined here as non-alphanumeric (not matching /[a-zA-Z0-9]/). This means alt-o will be forwarded to Neovim as "ø" rather than "M-ø". Note that this behavior can be changed by setting the alt setting of the globalSettings configuration to all, like this:

Making Firenvim ignore keys

You can make Firenvim ignore key presses (thus letting the browser handle them) by setting key-value pairs in globalSettings.ignoreKeys. The key needs to be the Neovim mode the key press should be ignored in and the value should be an array containing the textual representation of the key press you want ignored. If you want to ignore a key press in all modes, you can use all as mode key.

For example, if you want to make Firenvim ignore <C-1> and <C-2> in normal mode and <C--> in all modes to let your browser handle them, you should define ignoreKeys like this:

vim.g.firenvim_config = {
    globalSettings = {
        ignoreKeys = {
            all = { '<C-->' },
            normal = { '<C-1>', '<C-2>' }
        }
    }
}

Mode names are defined in Neovim's cursor_shape.c. Note that if the key press contains multiple modifiers, Shift needs to be first, Alt second, Control third and OS/Meta last (e.g. Ctrl+Alt+Shift+1 needs to be <SAC-1>). If your keyboard layout requires you to press shift in order to press numbers, shift should be present in the key representation (e.g. on french azerty keyboards, <C-1> should actually be <SC-1>).

Interacting with the page

You can execute javascript in the page by using firenvim#eval_js. The code has to be a valid ja