Firefox-UI-Fix/docs/Preference.md

Preference

Table of Contents

• Basics
• Default Config
• User Config
  • about:config
  • prefs.js
  • user.js
• Auto Config
• Using with User Custom CSS
• Sync
• Related Source file

Basics

Related Docs

• Firefox Source Docs: libpref

Key/Value

• Key:
  • Pref name
  • Type: 8-bit string
  • Convention is to use a dotted segmented form (Ex. browser.cache.disk.enable)
• Value:
  • Type: bool, 32-bit ints, 8-bit C string
  • When you need a float, use a string (Ex. general.smoothScroll.currentVelocityWeighting: "0.25")

Main Purpose

• Feature enable/disable flags (Ex. xpinstall.signatures.required).
• User preferences (Ex. things set from about:preferences)
• Internal application parameters (Ex. javascript.options.mem.nursery.max_kb).
• Application data (Ex. browser.onboarding.tour.onboarding-tour-addons.completed, services.sync.clients.lastSync).
• Things that might need locking in an enterprise installation.

Preference file RFC

Key information on the sets that can be used in the configuration file.

• pref(): Set default pref
  • sticky attr: same as sticky_pref()
  • locked attr: cannot change from default.
• sticky_pref(): Always logged even if the defaults match
• user_pref(): Set user pref

The following is a method of operating the configuration file parser.
See EBNF (Extended Backus-Naur form) if you want to know about syntax.

<pref-file>   = <pref>*;
<pref>        = <pref-spec> "(" <pref-name> "," <pref-value> <pref-attrs> ")" ";";
<pref-spec>   = "user_pref" | "pref" | "sticky_pref"; (* in default pref files *)
<pref-spec>   = "user_pref";                          (* in user pref files    *)
<pref-name>   = <string-literal>;
<pref-value>  = <string-literal> | "true" | "false" | <int-value>;
<int-value>   = <sign>? <int-literal>;
<sign>        = "+" | "-";
<int-literal> = [0-9]+ (and cannot be followed by [A-Za-z_]);
<string-literal> = ?
  A single or double-quoted string, with the following escape sequences
  allowed: "\"", "\'" "\\", "\n", "\r", "\xNN", "\uNNNN", where "\xNN" gives a raw byte
  value that is copied directly into an 8-bit string value, and "\uNNNN"
  gives a UTF-16 code unit that is converted to UTF-8 before being copied
  into an 8-bit string value. "\x00" and "\u0000" are disallowed because they
  would cause C++ code handling such strings to misbehave.
?;
<pref-attrs>  = ("," <pref-attr>)*       (* in default pref files   *)
              = <empty>;                 (* in user pref files      *)
<pref-attr>   = "sticky" | "locked";     (* default pref files only *)

Default Config

• modules/libpref/init/all.js: all products
• browser/app/profile/firefox.js: only firefox desktop

In release builds these are all put into omni.ja.

User Config

Related Docs

• mozillaZine: Editing configuration
• Support Mozilla: How to fix preferences that won't save
• Support Mozilla: Reset Firefox preferences to troubleshoot and fix problems
• UDN: A brief guide to Mozilla preferences

Restrictions

It can be defined using only user_pref().

User pref file syntax is slightly more restrictive than default pref file syntax. In user pref files user_pref definitions are allowed but pref and sticky_pref definitions are not, and attributes (such as locked) are not allowed.

File Path

prefs.js, user.js is located in the profile directory.

about:config

It is written to prefs.js in a way that can be set by the GUI.

• Support Mozilla: Configuration Editor for Firefox

prefs.js

Related Docs

• mozillaZine: Prefs.js file

Basics It exists in the profile directory, and is used to store settings that are changed from defaults or when users added new settings.

In general, do NOT edit prefs.js directly.

user.js

Related Docs

• mozillaZine: User.js file

Restrictions

A user.js file can make certain preference settings more or less "permanent" in a specific profile.

Once an entry for a preference setting exists in the user.js file, any change you make to that setting in the options and preference dialogs or via about:config will be lost when you restart your firefox because the user.js entry will override it.

You'll have to first delete or edit the user.js file to remove the entries before the preferences can be changed in the application.

Example

// user.js
user_pref("browser.cache.disk.enable", false);                      // Bool
user_pref("layout.css.prefers-color-scheme.content-override", 3);   // Int
user_pref("general.smoothScroll.currentVelocityWeighting", "0.12"); // String

Auto Config

Related Docs

• Support Mozilla: Customizing Firefox Using AutoConfig
• What is Autoconfig Startup Scripting (AKA userChrome.js)?
• UDN: Gecko Chrome
• UDN: JavaScript code modules
• UDN: Limitations of chrome scripts

Basics Customizations that cannot be done with add-on and User Custom CSS, such as adding browser UI elements directly or changing default behavior, must use Auto Config.

.mjs(ES6 Module) is also used in FF v102 or above.

• Bug 1432901 - Prototype loading ES6 Module as JSM

How to

• <FIREFOX_DIR>/defaults/pref/autoconfig.js

pref("general.config.filename", "config.js"); // alternative to "firefox.cfg", for using highlight
pref("general.config.obscure_value", 0);
pref("general.config.sandbox_enabled", false); // Sandbox needs to be disabled in release and Beta versions

• <FIREFOX_DIR>/config.js

// skip 1st line
try {
  const cmanifest = Cc['@mozilla.org/file/directory_service;1'].getService(Ci.nsIProperties).get('UChrm', Ci.nsIFile);
  cmanifest.append('utils');
  cmanifest.append('chrome.manifest');

  if(cmanifest.exists()){
    Components.manager.QueryInterface(Ci.nsIComponentRegistrar).autoRegister(cmanifest);
    ChromeUtils.import('chrome://userchromejs/content/boot.jsm');
  }

} catch(ex) {};

Example

• MrOtherGuy/fx-autoconfig
• xiaoxiaoflood/firefox-scripts

Using with User Custom CSS

Related Docs

• MDN: @supports
• UDN: CSS -moz-bool-pref() @supports function

Restrictions

Please refer to Doc: Restrictions.md's @support.

Example

Test each case by turning on/off the following settings.

• userChrome.navBar.red
• userChrome.navBar.margin

/* userChrome.css */

/* 1. If config is true */
@supports -moz-bool-pref("userChrome.navBar.red") {
  #nav-bar {
    background-color: red !important;
  }
}

/* 2. When any one of the config is true */
@supports -moz-bool-pref("userChrome.navBar.red") or -moz-bool-pref("userChrome.navBar.margin") {
  #nav-bar {
    background-color: red !important;
    margin-block: 20px;
  }
}

/* 3. Multiple configs must all be satisfied */
@supports -moz-bool-pref("userChrome.navBar.red") and -moz-bool-pref("userChrome.navBar.margin") {
  #nav-bar {
    background-color: red !important;
    margin-block: 20px;
  }
}

/* 4. 3's Other version */
@supports -moz-bool-pref("userChrome.navBar.red") {
  @supports -moz-bool-pref("userChrome.navBar.margin") {
    #nav-bar {
      background-color: red !important;
      margin-block: 20px;
    }
  }
}

/* 5. If not exist or false */
@supports not -moz-bool-pref("userChrome.navBar.red") {
  #nav-bar {
    background-color: blue !important;
  }
}

Sync

Related Docs

• Support Mozilla: Sync custom preferences

How to

Firefox Sync allows you to choose the types of data to sync across all devices.

The following options are required to sync custom configs.

• services.sync.prefs.dangerously_allow_arbitrary to true

Then, subsequently any pref can be pushed there by creating a remote with prefix.

• services.sync.prefs.sync.

Example

// user.js
user_pref("services.sync.prefs.dangerously_allow_arbitrary", true); // Must need

// Sync UI
user_pref("services.sync.prefs.sync.browser.uiCustomization.state", true);
user_pref("services.sync.prefs.sync.browser.uidensity", true);

Related Source file

• https://github.com/mozilla/gecko-dev/blob/master/modules/libpref/parser/src/lib.rs
• https://github.com/mozilla/gecko-dev/blob/master/extensions/pref/autoconfig/src/prefcalls.js