> For the complete documentation index, see [llms.txt](https://docs.sacruda.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sacruda.nl/developers/sacruda-apis/read-and-write-preferences.md).

# Read and write preferences

A Sacruda user has an object called the `UserPreferences` interface. It's a multidimensional object containing settings saved by Sacruda and its applications. Effectively anything non-critical the user can set is saved in here.

The User Daemon has a Svelte Store named `preferences`, which is initialised when the user logs in. Any changes made to this object are immediately saved to the server, and dispatched to other clients using Global Dispatch.

### Getting a preference

To get a preference in your app process, call `this.userPreferences()`. It returns the user preferences as a regular JS object:

```javascript
const accent = this.userPreferences()?.desktop.accent;
```

Assuming your editor supports it, you'll get autofill suggestions as you're typing, to figure out where to find the preference you're looking for.

### Updating the preferences

{% hint style="danger" %}
Updating the preferences IS RISKY. If you forget to return the preferences in the `update` callback, the user will lose their Sacruda preferences in an instant. I'll implement checks in the future to prevent this, but for the moment: **DO NOT FORGET TO RETURN THE PREFERENCES.**
{% endhint %}

The first way to change the user preferences is to call `this.userPreferences.update` in your process class. This function takes a callback that expects **the user preferences to be returned!** If you forget to return the user preferences after you've modified them, the preferences of the user WILL BE LOST. Be careful. Here's an example:

```javascript
this.userPreferences.update((v) => {
  v.desktop.accent = "#FF00FF";
  return v; // <- DO NOT FORGET TO RETURN!!!!
})
```

### Setting the preferences

If you've retrieved the user preferences using `this.userPreferences()`, and you've modified them in the midst of another operation, you can manually save them back into the variable using `this.userPreferences.set`:

```javascript
const preferences = this.userPreferences();

// Do something...

this.userPreferences.set(preferences);
```

{% hint style="warning" %}
You're not supposed to have a large amount of time between *getting* and *setting* the preferences, because of **desynchronisation**. This means that if you get the preferences, and something else changes them before you set them back, you'll accidentally roll back the state of the user's preferences, causing confusion and a potential loss of information. Perform time-intensive operations **before** getting the preferences to prevent this.
{% endhint %}

### App preferences

When you app's process is constructed, it creates a key in the `appPreferences` object. Take a look at this snippet from the base AppProcess source code:

{% code title="src/ts/apps/process.ts -> AppProcess -> constructor" %}

```typescript
const preferences = this.userPreferences();

if (!preferences.appPreferences[app.id]) {
  this.userPreferences.update((v) => {
    v.appPreferences[app.id] = {};

    return v;
  });
}
```

{% endcode %}

You can use this object to store settings specific to your applications. For example, the **File Manager** uses this to store the *view mode*.

#### Getting an app preference

Use this snippet to get app preferences of your app:

```javascript
const appPref = this.userPreferences().appPreferences[this.app.id];
```

#### Setting an app preference

Similarly, use this snippet to set a preference:

<pre class="language-javascript"><code class="lang-javascript">this.userPreferences.update((v) => {
  v.appPreferences[this.app.id].<a data-footnote-ref href="#user-content-fn-1">key</a> = <a data-footnote-ref href="#user-content-fn-2">value</a>;
  
  return v; // &#x3C;- DO NOT FORGET TO RETURN!!!!
})
</code></pre>

[^1]: The key of the preference you want to change

[^2]: The new value of the preference you're changing
