VimFx can optionally be configured using a text file—called a config file. This should be done by users who:
- prefer to configure things using text files.
- would like to add custom commands (and share custom commands!).
- would like to set special options.
- would like to make site-specific customizations.
- would like to customize which elements do and don’t get hints.
Look at the Share your config file wiki page for inspiration.
You get far just by copying and pasting.
VimFx requires you to provide either none or two files: config.js
and
frame.js
. Even though they are technically two, it’s easier to just say “the
config file,” (in singular) and think of config.js
is the actual config file
and frame.js
as an implementation detail. Both of these files are written in
JavaScript and are explained in more detail in the upcoming sections.
Follow these steps to get started:
-
Create a directory, anywhere on your hard drive. Examples:
- GNU/Linux:
~/.config/vimfx
or~/.vimfx
. - Windows:
c:\Users\you\vimfx
.
- GNU/Linux:
-
Create two empty plain text files in your directory, called
config.js
andframe.js
. -
Go to about:config and set the
config_file_directory
option to the path of the directory you created above. The path can be either absolute, such as/home/you/.config/vimfx
orC:\Users\you\vimfx
, or start with a~
(which is a shortcut to your home directory) such as~/.config/vimfx
or~\vimfx
. -
If you are running Firefox 57+, whitelist the
config_file_directory
by settingsecurity.sandbox.content.read_path_whitelist
(Linux and Windows) orsecurity.sandbox.content.mac.testing_read_path1
(OS X) to the absolute path of the config directory (~
not supported) ending on/
(or\
). You may have to restart the browser after modifying these prefs. -
Run the
gC
command in VimFx. That needs to be done any time you changeconfig_file_directory
, or editconfig.js
orframe.js
. This tells VimFx to reload the config file. If everything went well, a notification should appear (in the bottom-right corner of the window) telling you that the config file was successfully reloaded.
If you make errors in config.js
or frame.js
they will appear in the browser
console.
Remember to press gC
after you’ve edited config.js
or frame.js
to reload
them. A notification will appear telling you if there was any trouble
reloading or not. If there was, more information will be available in the
browser console.
Use console.log(...)
to inspect things. For example, try putting
console.log('This is vimfx:', vimfx)
in config.js
. Then, open the browser
console. There you should see an entry with the message “This is vimfx:” as
well as an interactive inspection of the vimfx
object.
Note: The browser console (default Firefox shortcut:
<c-J>
) is not the same as the web console (default Firefox
shortcut: <c-K>
). It’s easy to mix them up as a beginner!
Both config.js
and frame.js
have access to the following variables:
vimfx
: VimFx’sconfig.js
API orframe.js
API. You’ll probably only work with this object and not much else.console
: Let’s you print things to the browser console. Great for simple debugging.__dirname
: The full path to the config file directory, in a format that Firefox likes to work with. Useful if you want to import other files relative to the config file.Components
: This object is available to all add-ons, and is the main gateway to all of Firefox’s internals. This lets advanced users do basically anything, as if they had created a full regular Firefox add-on.Services
: Shortcuts to someComponents
stuff.content
: Available inframe.js
only. If you’ve ever done web development, this is basically the same aswindow
in regular web pages, orwindow
in the web console. This object lets you access web page content, for example by usingcontent.document.querySelector('a')
. SeeWindow
for more information.
frame.js
also has access to the entire standard Firefox frame script
environment, which might be interesting to advanced users.
This is the actual config file, where you’ll do most things. It is in this file
you add custom commands and set options, or whatever you’d like to do. However,
due to how Firefox is designed, it can not access web page content.
That’s why frame.js
exists.
Example code:
vimfx.set('hints.chars', 'abcdefghijklmnopqrstuvw xyz')
vimfx.set('custom.mode.normal.zoom_in', 'zi')
If you add custom commands, remember to add shortcuts to them!
Tip: If you already have made customizations in VimFx’s options page in the Add-ons Manager, you can use the “Export all” button there to copy all options as JSON. Paste it in your config file and either edit it, or iterate over it:
let options = {"hints.chars": "1234567 89"} // Pasted exported options.
Object.entries(options).forEach(([option, value]) => vimfx.set(option, value))
Due to how Firefox is designed, only frame.js
can access web page
content. On the other hand, it cannot acccess many things that config.js
can.
Instead of simply doing everything on config.js
, you need to send messages
between config.js
and frame.js
.
Typically, all you do in frame.js
is listening for messages from config.js
and reponding to those messages with some data from the current web page, which
only frame.js
has access to. The vimfx.send(...)
documentation has an
example of this.
Even if you don’t need frame.js
right now, the file still must exist if
config.js
exists. Simply leave it blank.
(config.js
actually can access web page content in some circumstances.
However, that’s a legacy Firefox feature that can stop working at any time, and
can even slow Firefox down! Don’t use such methods if you come across them.)
- Every time VimFx starts up. In other words, when Firefox starts up and when you update VimFx (or disable and then enable it).
- Every time you use the
gC
command to reload the config file.
“Executing the config file” means running config.js
once and frame.js
for
each open tab. frame.js
also runs every time you open a new tab.
(See also the shutdown
event.)
Electrolysis (e10s) introduced a process sandbox; a security feature limiting
the impact of exploits in a content process. With the release of Firefox
Quantum (57) the sandbox was tightened to disallow file system reads, which
requires frame.js
and other files accessed from a content process to be
whitelisted. Mozilla provides a pref,
security.sandbox.content.read_path_whitelist
, that accepts a comma-separated
list of paths. If a path ends with a path separator (i.e. /
or \
), the
whole directory will become whitelisted. This pref is unavailable on OS X,
where you instead get two undocumented prefs,
security.sandbox.content.mac.testing_read_path1
and
security.sandbox.content.mac.testing_read_path2
, each accepting one directory
path to whitelist.
If you want to read other files from the file system from frame.js
, place
them inside the whitelisted directory or add their paths to the
read_path_whitelist
. Analogously, a write_path_whitelist
exists on non-OSX
systems; OS X users may be able to write to the extensions
and chrome
subdirectories inside the profile directory instead.
Weakening the sandbox by setting security.sandbox.content.level
to 2 is not
recommended, as this will open up a potentially devastating security hole.