Skip to main content
A schema is a plain TypeScript object where each key maps to a schema value — a primitive constructor, a keyring() field, an optional() wrapper, a nested object, or a single-element array. You pass the schema to defineConfig() once at module level, and tauri-plugin-configurate derives all TypeScript types from it automatically. You never have to write the config interface by hand.

​
defineConfig(schema)

Validates and freezes a schema object at runtime. The return value is the same object you passed in — defineConfig() exists so TypeScript can infer the generic parameter S and propagate it into every downstream type. 
function defineConfig<S extends SchemaObject>(schema: S): S
​
schema
S extends SchemaObject
required
A plain object where each value is a primitive constructor (String, Number, Boolean), a keyring() field, an optional() field, a nested schema object, or a single-element array like [String]. Arrays must contain exactly one element.
​
returns
S
The same schema object passed in, typed as S. Assign the return value to a const so that TypeScript treats it as a literal type rather than a widened one.
At runtime, defineConfig() performs two checks and throws on failure:
  • Every schema array ([String], [Number], etc.) must contain exactly one element.
  • Every keyring() id within the schema must be unique.
import { defineConfig, keyring, optional } from "tauri-plugin-configurate-api";

const schema = defineConfig({
  theme: String,
  fontSize: optional(Number),
  apiKey: keyring(String, { id: "api-key" }),
  database: {
    host: String,
    port: Number,
    password: keyring(String, { id: "db-password" }),
  },
  tags: [String],
});
TypeScript enforces unique keyring IDs at the type level via HasDuplicateKeyringIds<S>. If you accidentally reuse an ID, the TypeScript compiler rejects the call before it reaches the runtime check.

​
keyring(typeCtor, opts)

Marks a schema field as OS keyring-protected. The value is stored in the operating system’s credential store (not in the config file) and is returned as null when loading without an unlock step. 
function keyring<T, Id extends string>(
  typeCtor: StringConstructor | NumberConstructor | BooleanConstructor,
  opts: { id: Id }
): KeyringField<T, Id>
​
typeCtor
StringConstructor | NumberConstructor | BooleanConstructor
required
The JavaScript constructor function for the value’s type: String, Number, or Boolean.
​
opts.id
string
required
Unique identifier for this keyring entry within the schema. Must not be empty. Must not contain / — the slash is used as a separator in the keyring user string ({account}/{id}), so including it would create an ambiguous path.
​
returns
KeyringField<T, Id>
A branded marker object. At runtime this object is a plain record with internal brand keys; its shape matters only to the plugin internals and the TypeScript type system.
const schema = defineConfig({
  apiKey: keyring(String, { id: "api-key" }),
  retryCount: keyring(Number, { id: "retry-count" }),
  isPremium: keyring(Boolean, { id: "premium-flag" }),
});
Two keyring() calls in the same schema must not share the same id. Reusing an id will cause defineConfig() to throw at runtime and produce a TypeScript compile error.

​
optional(schema)

Wraps any schema value to mark it as optional. An optional field may be absent from the stored config; it does not fail schema validation when missing, and its inferred TypeScript type includes | undefined. 
function optional<V>(schema: V): OptionalField<V>
​
schema
V
required
Any valid schema value: a primitive constructor, a keyring() field, a nested schema object, or a single-element array. You cannot nest optional() inside another optional().
​
returns
OptionalField<V>
A branded marker object that wraps schema and signals optionality to the type inference utilities and runtime validation.
const schema = defineConfig({
  theme: String,                                       // required string
  fontSize: optional(Number),                         // optional number
  apiKey: optional(keyring(String, { id: "key" })),   // optional keyring field
  proxy: optional({ host: String, port: Number }),    // optional nested object
  aliases: optional([String]),                        // optional array of strings
});

​
Schema types reference

The table below shows every schema value type and the TypeScript type it produces through InferUnlocked<S> and InferLocked<S>.
Schema valueInferUnlocked<S>InferLocked<S>
Stringstringstring
Numbernumbernumber
Booleanbooleanboolean
keyring(String, ...)stringnull
keyring(Number, ...)numbernull
keyring(Boolean, ...)booleannull
optional(String)string | undefinedstring | undefined
optional(keyring(String, ...))string | undefinednull | undefined
{ key: String }{ key: string }{ key: string }
[String]string[]string[]
[keyring(String, ...)]string[]null[]

​
Type inference utilities

Two utility types let you reference the inferred config shape in your own code:

​
InferUnlocked<S>

Produces the full config type with all keyring fields resolved to their real value types. Use this when you have an unlocked config or when constructing data to pass to create(), save(), or reset(). 
import type { InferUnlocked } from "tauri-plugin-configurate-api";

type AppConfig = InferUnlocked<typeof schema>;
// { theme: string; fontSize?: number; apiKey: string; database: { host: string; port: number; password: string } }

function buildDefaults(): Partial<AppConfig> {
  return { theme: "light", fontSize: 14 };
}

​
InferLocked<S>

Produces the config type with all keyring fields replaced by null. This is the type of LockedConfig<S>.data — what you see when you call load().run() without unlocking. 
import type { InferLocked } from "tauri-plugin-configurate-api";

type LockedAppConfig = InferLocked<typeof schema>;
// { theme: string; fontSize?: number; apiKey: null; database: { host: string; port: number; password: null } }