> ## Documentation Index
> Fetch the complete documentation index at: https://configurate.crystaworld.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Storage Providers: JSON, YAML, TOML, and Encrypted Binary

> Choose how tauri-plugin-configurate stores your config files: human-readable JSON, YAML, or TOML, or encrypted binary using XChaCha20-Poly1305.

A provider defines the storage format and file extension used when the plugin reads and writes your configuration to disk. You pass a provider to the `Configurate` constructor, and the plugin handles all serialization and deserialization automatically. Choose the provider that best matches your requirements for readability, compatibility, and security.

## `JsonProvider()`

JSON is the default choice for most applications. Files are pretty-printed and human-readable, which makes them easy to inspect and edit manually.

```typescript theme={null}
import { JsonProvider } from "tauri-plugin-configurate-api";

JsonProvider()
```

Config files are written with standard JSON formatting. The file extension is `.json`.

## `YmlProvider()`

YAML storage is useful when your users or developers prefer a less verbose format, or when you want to support inline comments in manually edited files.

```typescript theme={null}
import { YmlProvider } from "tauri-plugin-configurate-api";

YmlProvider()
```

Config files use the `.yml` extension.

<Warning>
  Only import YAML from trusted sources. Untrusted YAML can expand via anchors
  and aliases, potentially consuming large amounts of memory. Prefer JSON or
  TOML when importing config from user-supplied input.
</Warning>

## `TomlProvider()`

TOML storage is a good fit for developer-facing configuration or tools that integrate with the Rust ecosystem.

```typescript theme={null}
import { TomlProvider } from "tauri-plugin-configurate-api";

TomlProvider()
```

Config files use the `.toml` extension.

<Warning>
  TOML has no native `null` type. When the plugin writes a config object, any
  field whose value is `null` is **silently omitted** from the TOML file. On
  the next `load()`, that key will be absent from the returned data. Mark
  fields that can be absent as `optional()` in your schema, and use the
  `defaults` option in the `Configurate` constructor to supply fallback values
  on read.
</Warning>

## `BinaryProvider(opts?)`

Binary storage serializes your configuration as compact JSON bytes and optionally encrypts them using **XChaCha20-Poly1305**. Use this provider when you need to protect configuration data at rest.

```typescript theme={null}
import { BinaryProvider } from "tauri-plugin-configurate-api";

// Unencrypted compact JSON bytes
BinaryProvider()

// Encrypted with SHA-256 key derivation — for high-entropy keys only
BinaryProvider({ encryptionKey: "key" })

// Encrypted with Argon2id key derivation — for user passwords
BinaryProvider({ encryptionKey: "key", kdf: "argon2" })
```

### Options

| Option          | Type                   | Default     | Description                                                        |
| --------------- | ---------------------- | ----------- | ------------------------------------------------------------------ |
| `encryptionKey` | `string?`              | `undefined` | The encryption key. Omit to store unencrypted binary.              |
| `kdf`           | `"sha256" \| "argon2"` | `"sha256"`  | Key derivation function used to stretch the key before encryption. |

### Key derivation

When you provide an `encryptionKey`, the plugin derives the actual cipher key using one of two functions:

* **`"sha256"` (default):** Applies a single SHA-256 hash to the key string. This is fast and suitable only when the key has high entropy — for example, a random token stored in the OS keyring. Do not use this mode with a user-typed password.
* **`"argon2"`:** Applies Argon2id with a per-file random salt. This is designed for password-based encryption and is significantly more resistant to brute-force attacks.

<Tip>
  If your `encryptionKey` comes from a user password or any low-entropy input,
  always use `kdf: "argon2"`. The default SHA-256 derivation provides no
  protection against dictionary attacks.
</Tip>

Without an `encryptionKey`, `BinaryProvider()` writes compact (non-pretty-printed) JSON bytes. The file is not encrypted, but its binary format may deter casual inspection. Use this mode when you want a compact on-disk footprint without the overhead of encryption.