https://github.com/dwarfmaster/arkenfox-nixos
Utilities to use arkenfox/user.js in NixOS
https://github.com/dwarfmaster/arkenfox-nixos
Last synced: about 1 year ago
JSON representation
Utilities to use arkenfox/user.js in NixOS
- Host: GitHub
- URL: https://github.com/dwarfmaster/arkenfox-nixos
- Owner: dwarfmaster
- License: mit
- Created: 2022-03-11T11:49:26.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-03-23T01:44:49.000Z (over 1 year ago)
- Last Synced: 2025-03-30T19:11:22.572Z (about 1 year ago)
- Language: Nix
- Size: 564 KB
- Stars: 79
- Watchers: 4
- Forks: 16
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Arkenfox user.js module for NixOS + home-manager
## Motivation
Firefox's `user.js` can be used to store preferences and settings for Firefox,
but it is painful to manually edit. There is a popular `user.js` optimised for
ease of edition and hardening :
[Arkenfox's](https://github.com/arkenfox/user.js).
If one want to directly use it, there already is an option in home-manager to
use a `user.js` : `programs.firefox.profiles..extraConfig` and
`programs.firefox.profiles..settings`.
The problem with directly using Arkenfox's `user.js` is that handling updates to
file after having gone through it to edit your preferences is a bit of a pain.
In order to improve the situation, we implemented a script that parses
Arkenfox's `user.js` and generate a home-manager module that allows setting the
preferences using the merge algorithm of the NixOS module system. Furthermore,
it keeps the edits outside the generated module. Any drift between the
settings and the `user.js` will be caught by the module type-system.
## Outputs
This flake exports a few things :
- the script used for the extraction as `packages..arkenfox-extractor`.
- the home-manager module as `hmModules.arkenfox`.
- a rendered documentation of each supported `user.js` version as
`packages..arkenfox-v-doc-static`. Here version can be either
a numeric one like `103_0` or `master`.
## Home-manager module
To enable the module, you need to set both `programs.firefox.arkenfox.enable` to
true and `programs.firefox.arkenfox.version` to the version you want to use.
Ideally the version used is the same as Firefox's, but may differ if arkenfox
hasn't yet been updated, or you want to keep your previous settings with the new
Firefox version. In the case the versions do not match, a warning will be
displayed when generating the configuration.
Then the settings can be set profile-by-profile using
`programs.firefox.profiles..arkenfox`. The `user.js` file is subdivided
into sections, subsections and individual settings that all have a default
value, and may be commented or not. All this is present in the module. A setting
can be set with `...value` and
enabled with `...enable`.
Sections and subsections can also be enabled and disabled. A setting value is
only set if both its sections and subsection are enabled. Furthermore, a top
level `enable` flag is present.
Since Arkenfox's settings are *very* opinionated and shouldn't be used unless
they've been reviewed and agreed with, both the top level `enable` flag and all
sections `enable` flags are false by default. On the other hand, the
subsections `enable` flags are true by default. There is a `enableAllSections`
top level flag that makes all sections enabled by default if this is what you
want.
For example, if you want to enable the `TOPLEVEL`, `STARTUP` and `GEOLOCATION`
sections, but still have Firefox check if it is the default browser, and you
want to enable the search region setting that is commented in the default
`user.js` but keep its value, you would do:
```nix
{
programs.firefox = {
enable = true;
arkenfox = {
enable = true;
version = "103.0";
};
profiles.Default.arkenfox = {
enable = true;
"0000".enable = true;
"0001" = {
enable = true;
"0101"."browser.shell.checkDefaultBrowser".value = true;
};
"0002" = {
enable = true;
"0204"."browser.search.region".enable = true;
};
};
};
}
```
## Documentation
Finding the section and subsection numbers and the option names can be a bit
complicated. The authoritative source of truth is of course the `user.js` file
on Arkenfox's GitHub, which you should read, at least the section you enable.
For better usability, the metadata extracted is also used to generate a HTML
file that may be more agreeable looking through.
Targets `programs..arkenfox-v-doc-static` will build this
`html` file. An example of a rendered documentation (WARNING: often outdated)
can be found [there](https://arkenfox.dwarfmaster.net). Each setting is
presented as a table with a checkbox indicating if it is enabled by default, its
name, and its default value.
You can build the documentation without copying the flake using (for example):
```shell
nix build "github:dwarfmaster/arkenfox-nixos#arkenfox-v103_0-doc-static"
```