> For AI agents: the complete documentation index is available at https://docs.flashnerd.com/llms.txt, the full documentation bundle is available at https://docs.flashnerd.com/llms-full.txt.

# User preferences

Include selected app preferences in a package only when the user intends to transfer them. Each property is optional. A new-deck file normally omits this file so importing learning material does not also change app preferences.

Flashnerd exports and restores Appearance (`appLocale`, `appTheme`, `hapticFeedbackEnabled`) and Review Settings (`reviewAheadLimit`, `nextDayStartsAtMinutes`). These five properties are the recognized portable preferences. Extra properties are ignored on import.

## Location

`preferences/user.json` is one optional file with this exact name. It contains a single JSON object, not JSON Lines or an array. Pretty-printed JSON is valid in this file. Omit the file when there are no preferences to transfer.

## Basic example

Save this object in `preferences/user.json`:

```json
{
  "appLocale": "en",
  "appTheme": "system",
  "reviewAheadLimit": 30,
  "nextDayStartsAtMinutes": 240
}
```

`240` means the review day begins at 04:00 in the device's local timezone. `reviewAheadLimit: 30` sets a 30-minute review-ahead window.

## Full example

Copy <a href="https://docs.flashnerd.com/examples/flashnerd-format/full/preferences/user.json" download>the full user.json</a>. This single object fills all five portable preference keys and can stay pretty-printed in the package.

```json
{
  "appLocale": "ja",
  "appTheme": "light",
  "hapticFeedbackEnabled": false,
  "reviewAheadLimit": 30,
  "nextDayStartsAtMinutes": 180
}
```

## Fields

All keys are optional. Omission leaves the value absent; it does not write a default or instruct the importer to clear an existing setting.

| Key                      | Type / allowed values        | Meaning                                                                  | Explicit `null` in the reader |
| ------------------------ | ---------------------------- | ------------------------------------------------------------------------ | ----------------------------- |
| `appLocale`              | String                       | BCP-47 locale tag, for example `en` or `zh-Hant-TW`.                     | Treated as omitted.           |
| `appTheme`               | `light`, `dark`, `system`    | Appearance theme.                                                        | Rejected.                     |
| `hapticFeedbackEnabled`  | Boolean                      | Enable haptic feedback.                                                  | Rejected.                     |
| `reviewAheadLimit`       | Integer, at least `0`        | Review-ahead window in minutes.                                          | Rejected.                     |
| `nextDayStartsAtMinutes` | Integer, `0`–`360` inclusive | Review-day boundary in minutes after midnight, from 00:00 through 06:00. | Rejected.                     |

The format checks `appLocale` as a string; it does not validate a catalog of locale names.

The five keys listed above are read and applied. Other properties are ignored, including when their values are `null` or they accompany supported fields, and are not retained in later exports. Recognized keys still follow the types and null rules in the table; among them, only `appLocale` accepts explicit `null`.

## Relationships and optional sections

This file has no `id`, `createdAt`, or `updatedAt`, and references no other package record. Appearance and Review Settings are logical groups, not nested JSON objects: write their keys directly at the top level.

Either group can be present on its own. When the app applies a group, properties omitted from that group retain the destination's existing values. Explicit `false` and `0` in recognized fields count as supplied values. An empty object `{}`, `{"appLocale":null}`, or an object containing only ignored properties has no settings to apply; if that is the package's only payload, validation rejects it. These preference objects can accompany valid records. Account, authentication, and billing data have no supported fields here.

Preference field errors identify `preferences/user.json`. A root-level `user.json` is not read.

## Additional example: change only the theme

This is a complete alternative `preferences/user.json` file:

```json
{"appTheme":"dark"}
```

To transfer only the review-day boundary, use this complete alternative:

```json
{"nextDayStartsAtMinutes":240}
```

Do not concatenate these examples into separate lines in the file. Combine selected keys into one JSON object.

## Schema

<a href="https://docs.flashnerd.com/examples/flashnerd-format/schemas/user_preferences.schema.json" download>User-preferences schema</a> and [complete package layout](https://docs.flashnerd.com/reference/flashnerd-format/package.md).