Skip to main content
A provider tells Configurate how to serialize and persist your config data. You pass one to the Configurate constructor as the provider option. Providers are opaque branded values — you create them by calling one of the five factory functions exported from tauri-plugin-configurate-api. 
import {
  JsonProvider,
  YmlProvider,
  TomlProvider,
  BinaryProvider,
  SqliteProvider,
} from "tauri-plugin-configurate-api";

​
Provider comparison

ProviderFormatEncryptedHuman-readableNull support
JsonProvider()JSONNoYesYes
YmlProvider()YAMLNoYesYes
TomlProvider()TOMLNoYesPartial — see note below
BinaryProvider()Compact JSON bytesNoNoYes
BinaryProvider({ encryptionKey })XChaCha20-Poly1305YesNoYes
SqliteProvider()SQLite databaseNoQueryableYes

​
JsonProvider

JsonProvider() stores config data as a pretty-printed JSON file. It is the most portable format and the simplest choice for configs that do not need encryption or human-hostile storage. 
import { Configurate, JsonProvider, BaseDirectory } from "tauri-plugin-configurate-api";

const config = new Configurate({
  schema: appSchema,
  fileName: "settings.json",
  baseDir: BaseDirectory.AppConfig,
  provider: JsonProvider(),
});
Files are written atomically using a temp-file-then-rename strategy to minimize the risk of partial writes.

​
YmlProvider

YmlProvider() stores config data as a YAML file. YAML is human-readable and supports comments if the file is edited by hand. 
provider: YmlProvider()
YAML is converted through serde_yml on the Rust side. YAML null values round-trip correctly.

​
TomlProvider

TomlProvider() stores config data as a TOML file. TOML is readable and a common choice for developer tooling config files. 
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. If you set a required (non-optional) field to null and save, that field will disappear on reload.Additionally, null values inside arrays are rejected outright with an error — TOML cannot represent them at all.Use optional() schema fields to model nullable values, and rely on the defaults option in Configurate to supply fallback values on read. Do not store null in non-optional fields with TomlProvider.

​
BinaryProvider

BinaryProvider() serializes config data to a compact (non-pretty) JSON byte stream. Without an encryptionKey, the file is not encrypted — this is useful when you want a smaller file without whitespace, but do not need confidentiality. 
provider: BinaryProvider()             // unencrypted — compact JSON bytes
BinaryProvider() without an encryptionKey provides no confidentiality. Anyone with file system access can read the config. Use BinaryProvider({ encryptionKey }) or the OS keyring for sensitive values.
The on-disk format for unencrypted BinaryProvider() changed in v0.2.3. Files written by v0.2.2 or earlier must be re-created after upgrading. Encrypted binary files are not affected.

​
Encryption with SHA-256 KDF

Pass an encryptionKey string to enable XChaCha20-Poly1305 authenticated encryption. The 32-byte cipher key is derived from your key string by SHA-256, so any high-entropy string is suitable. 
provider: BinaryProvider({ encryptionKey: "my-encryption-key" })
On-disk format: [24-byte random nonce][ciphertext + 16-byte Poly1305 authentication tag]
  • A fresh random nonce is generated on every write, so identical data produces different ciphertext.
  • The Poly1305 tag detects tampering — a modified file fails to decrypt with a clear error.
  • This is the default KDF ("sha256"). It is fast but does not provide brute-force resistance; use a high-entropy key.

​
Encryption with Argon2id KDF

Set kdf: "argon2" to derive the cipher key using Argon2id instead of SHA-256. Argon2id is a memory-hard password-based KDF that makes brute-force attacks expensive, making it suitable when the encryptionKey is a human-chosen password. 
provider: BinaryProvider({ encryptionKey: "user-password", kdf: "argon2" })
On-disk format: [16-byte random salt][24-byte random nonce][ciphertext + 16-byte Poly1305 tag]
  • A new random salt is generated on every write so the same password produces different ciphertext.
  • Parameters: m=19456 KiB, t=2, p=1 (Argon2id defaults — moderate cost).
  • Write operations are noticeably slower than SHA-256 due to the intentional memory-hardness.

​
BinaryProvider options summary

OptionTypeDefaultDescription
encryptionKeystringundefinedKey or password for encryption. Omit for unencrypted.
kdf"sha256" | "argon2""sha256"Key derivation function when encryptionKey is set.

​
SqliteProvider

SqliteProvider() stores config data in a SQLite database file. Schema fields are materialized as typed SQLite columns, making the data queryable with standard SQLite tools. 
provider: SqliteProvider()
// Uses defaults: dbName="configurate.db", tableName="configurate_configs"

provider: SqliteProvider({ dbName: "app.db", tableName: "settings" })

​
Options

OptionTypeDefaultDescription
dbNamestring"configurate.db"SQLite database file name within the resolved base directory.
tableNamestring"configurate_configs"Table name inside the database. Only [A-Za-z0-9_] is allowed.

​
How SQLite storage works

The plugin derives a column for each leaf field in the schema:
  • String fields → TEXT columns
  • Number fields → REAL columns
  • Boolean fields → INTEGER columns (0/1)
  • keyring() fields → TEXT columns but always stored as NULL (the secret lives in the OS keyring)
  • Array and nested-object fields → stored as JSON text in a single TEXT column
The table is created with CREATE TABLE IF NOT EXISTS on first write. New schema fields are added via ALTER TABLE ADD COLUMN automatically when the schema evolves — existing rows are not affected. SQLite uses WAL journal mode and PRAGMA synchronous=NORMAL for durability without excessive fsync overhead.
The rolling backup (backup: true) option has no effect on SqliteProvider — SQLite manages its own durability through WAL mode.watchExternal() (file watching for external changes) also does not work with SqliteProvider and will throw if called.

​
Choosing a provider

JsonProvider

Best default choice. Human-readable, portable, widely supported. Use when the config file might be edited by hand or shared between tools.

YmlProvider

Good for YAML-native ecosystems. Slightly more readable than JSON for nested data. Avoid if null handling matters and you use TOML-adjacent tooling.

BinaryProvider (encrypted)

Use when the config file must be opaque on disk — e.g. for storing tokens or credentials that cannot go in the OS keyring. Prefer Argon2id for user-supplied passwords.

SqliteProvider

Use when you need queryable storage, plan to store many config entries in one database, or want SQLite’s built-in transactional durability.

Build docs developers (and LLMs) love

Get started for freeTalk to us