Storage Provider Functions: JSON, YAML, TOML, Binary

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.

function JsonProvider(): ConfigurateProvider

ConfigurateProvider

A frozen provider object with kind: "json".

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.

function YmlProvider(): ConfigurateProvider

ConfigurateProvider

A frozen provider object with kind: "yml".

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.

function TomlProvider(): ConfigurateProvider

ConfigurateProvider

A frozen provider object with kind: "toml".

import { TomlProvider } from "tauri-plugin-configurate-api";

const provider = TomlProvider();

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.

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.

function BinaryProvider(opts?: {
  encryptionKey?: string;
  kdf?: "sha256" | "argon2";
}): ConfigurateProvider

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.

"sha256" | "argon2"

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.

ConfigurateProvider

A frozen provider object with kind: "binary" and the supplied options.

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" });

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.

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.

Full usage examples

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" }),
});

TypeScript API

Rust API

Storage Provider Functions: JSON, YAML, TOML, Binary

Providers at a glance

JsonProvider()

YmlProvider()

TomlProvider()

BinaryProvider(opts?)

Full usage examples

​Providers at a glance

​JsonProvider()

​YmlProvider()

​TomlProvider()

​BinaryProvider(opts?)

​Full usage examples

Providers at a glance

JsonProvider()

YmlProvider()

TomlProvider()

BinaryProvider(opts?)

Full usage examples