> ## 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 Provider Functions: JSON, YAML, TOML, Binary

> Reference for JsonProvider(), YmlProvider(), TomlProvider(), and BinaryProvider() — factory functions that set the storage format for your config files.

A provider controls the file format and optional encryption that tauri-plugin-configurate uses when reading and writing your config. You create a provider by calling one of the four factory functions below and passing the result to the `provider` option of the `Configurate` constructor. Each factory returns a frozen, branded `ConfigurateProvider` object; you cannot construct one by hand.

## Providers at a glance

| Factory            | Format | Encrypted | Human-readable |
| ------------------ | ------ | --------- | -------------- |
| `JsonProvider()`   | JSON   | No        | Yes            |
| `YmlProvider()`    | YAML   | No        | Yes            |
| `TomlProvider()`   | TOML   | No        | Yes            |
| `BinaryProvider()` | Binary | Optional  | No             |

***

## JsonProvider()

Creates a plain JSON storage provider. Config files are pretty-printed, making them easy to inspect in a text editor or version control system.

```typescript theme={null}
function JsonProvider(): ConfigurateProvider
```

<ResponseField name="returns" type="ConfigurateProvider">
  A frozen provider object with `kind: "json"`.
</ResponseField>

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

const provider = JsonProvider();
```

***

## YmlProvider()

Creates a YAML storage provider. Config files are written as standard YAML, which supports comments and is widely used for human-authored configuration.

```typescript theme={null}
function YmlProvider(): ConfigurateProvider
```

<ResponseField name="returns" type="ConfigurateProvider">
  A frozen provider object with `kind: "yml"`.
</ResponseField>

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

const provider = YmlProvider();
```

***

## TomlProvider()

Creates a TOML storage provider. Config files are written as TOML, which is favored for its strict specification and clear key-value syntax.

```typescript theme={null}
function TomlProvider(): ConfigurateProvider
```

<ResponseField name="returns" type="ConfigurateProvider">
  A frozen provider object with `kind: "toml"`.
</ResponseField>

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

const provider = TomlProvider();
```

<Warning>
  TOML has no native `null` type. When a config object is saved, 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. Use `optional()` schema fields to model nullable values and rely on the `defaults` constructor option to supply fallback values on read. Setting a non-optional field to `null` and saving it will cause that field to disappear on the next load.
</Warning>

***

## BinaryProvider(opts?)

Creates a binary storage provider with optional XChaCha20-Poly1305 encryption. Without an `encryptionKey`, data is serialized to compact JSON bytes but not encrypted. With an `encryptionKey`, the bytes are encrypted before writing.

```typescript theme={null}
function BinaryProvider(opts?: {
  encryptionKey?: string;
  kdf?: "sha256" | "argon2";
}): ConfigurateProvider
```

<ParamField path="opts.encryptionKey" type="string">
  Encryption key passed to the key derivation function. Omit this option entirely to store data unencrypted (compact binary JSON). When provided, the file is XChaCha20-Poly1305-encrypted.
</ParamField>

<ParamField path="opts.kdf" type="&#x22;sha256&#x22; | &#x22;argon2&#x22;">
  Key derivation function to apply to `encryptionKey` before using it for encryption. Defaults to `"sha256"` when omitted.

  * **`"sha256"`** — Derives the key with a single SHA-256 hash. Fast and appropriate when `encryptionKey` is already a high-entropy random value (for example, a key retrieved from the OS keyring). Do **not** use this with a user-entered password.
  * **`"argon2"`** — Derives the key with Argon2id, using a per-file random salt stored in the file header. Use this when `encryptionKey` is a user-entered password or any low-entropy string.
</ParamField>

<ResponseField name="returns" type="ConfigurateProvider">
  A frozen provider object with `kind: "binary"` and the supplied options.
</ResponseField>

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

// Unencrypted binary (compact JSON bytes)
BinaryProvider();

// Encrypted — high-entropy random key, SHA-256 KDF (default)
BinaryProvider({ encryptionKey: "random-high-entropy-key" });

// Encrypted — user password, Argon2id KDF
BinaryProvider({ encryptionKey: "user-password", kdf: "argon2" });
```

<Tip>
  Store the encryption key itself in the OS keyring using a `keyring()` schema field, then pass it to `BinaryProvider` at startup. This way the key is never hard-coded in your bundle.
</Tip>

<Note>
  `BinaryProvider` files are not human-readable. If you need to inspect or migrate the data, use `config.exportAs("json")` to convert the current content to a readable format.
</Note>

***

## Full usage examples

```typescript theme={null}
import {
  Configurate,
  defineConfig,
  JsonProvider,
  YmlProvider,
  TomlProvider,
  BinaryProvider,
} from "tauri-plugin-configurate-api";
import { BaseDirectory } from "@tauri-apps/api/path";

const schema = defineConfig({ theme: String, fontSize: Number });

// JSON
const jsonConfig = new Configurate({
  schema,
  fileName: "app.json",
  baseDir: BaseDirectory.AppConfig,
  provider: JsonProvider(),
});

// YAML
const ymlConfig = new Configurate({
  schema,
  fileName: "app.yml",
  baseDir: BaseDirectory.AppConfig,
  provider: YmlProvider(),
});

// TOML
const tomlConfig = new Configurate({
  schema,
  fileName: "app.toml",
  baseDir: BaseDirectory.AppConfig,
  provider: TomlProvider(),
});

// Binary — no encryption
const binaryConfig = new Configurate({
  schema,
  fileName: "app.bin",
  baseDir: BaseDirectory.AppConfig,
  provider: BinaryProvider(),
});

// Binary — encrypted with a high-entropy key
const encryptedConfig = new Configurate({
  schema,
  fileName: "app.bin",
  baseDir: BaseDirectory.AppConfig,
  provider: BinaryProvider({ encryptionKey: "random-high-entropy-key" }),
});

// Binary — password-based encryption
const passwordConfig = new Configurate({
  schema,
  fileName: "app.bin",
  baseDir: BaseDirectory.AppConfig,
  provider: BinaryProvider({ encryptionKey: "user-password", kdf: "argon2" }),
});
```