# Preferences

This documentation aims at giving an overview of the preferences API used in DevTools, it
is not an actual documentation about the list of preferences available in DevTools.

## Overview

Preferences allows you to save and read strings, numbers, booleans to the preferences
store, which is tied to a profile. A preference can also have a default value.

## Preference types

DevTools relies on nsIPrefBranch for preferences, which supports different types of
preferences:
* `Int`
* `Boolean`
* `Char`
* `String`

Choose the appropriate type depending on the data you need to store. If you need to store
a JavaScript object or array, the recommended way is to:
* use a `String` type preference
* use JSON.stringify to save
* use JSON.parse to read

Note that nsIPrefBranch also supports a `Complex` type.

## Reading and updating preferences

### API docs for nsIPrefBranch and nsIPrefService

DevTools relies on Services.pref to handle preferences. You can access the API docs for
this service at:
* [Source for nsIPrefBranch](https://searchfox.org/mozilla-central/source/modules/libpref/nsIPrefBranch.idl)
* [Source for nsIPrefService](https://searchfox.org/mozilla-central/source/modules/libpref/nsIPrefService.idl)

### Services.pref.get* and Services.pref.set*

The main APIs you will have to know and use are getters and setters.
* `Services.pref.getIntPref(prefName, defaultValue);` This method will throw if the
preference cannot be found and you didn't pass a default value!
* `Services.pref.setIntPref(prefName, prefValue)` This method will throw if the provided
value does not match the preference type!

These APIs are very similar for each preference type.

## Create a new preference

Debugger-specific preferences should go in
devtools/client/preferences/debugger.js. Beyond that, most new preferences
should go in browser/app/profile/firefox.js, which is for desktop Firefox only.
If a preference should be available even when the client for DevTools is not
shipped (for instance on Fennec) it should go in modules/libpref/init/all.js,
which is for preferences that go in all products.

## Inspect preferences

Depending on the project you are working on, preferences are stored differently but can
always be inspected.

In Firefox, you can open a tab to about:config and search by preference name.