Utility Functions: configDiff and MigrationStep Reference

tauri-plugin-configurate ships two utility exports that complement the main Configurate class. configDiff() is a standalone function that computes a structural diff between any two config-shaped objects — useful for logging, auditing, or selectively reacting to changes. MigrationStep is the interface you implement to upgrade stored configs from an older schema version to a newer one.

configDiff(oldData, newData)

Computes a structural diff between two config objects and returns an array of change descriptors. Nested objects are compared recursively, and each change is reported at its deepest differing path using dot-separated notation.

function configDiff(
  oldData: Record<string, unknown>,
  newData: Record<string, unknown>,
): DiffEntry[]

Record<string, unknown>

required

The baseline config object — the “before” state.

Record<string, unknown>

required

The updated config object — the “after” state.

DiffEntry[]

An array of DiffEntry objects, one for each key that was added, removed, or changed. The array is empty when the two objects are deeply equal. Order follows the iteration order of the union of both objects’ keys.

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

const changes = configDiff(
  { theme: "light", fontSize: 14 },
  { theme: "dark", fontSize: 14, lang: "en" },
);
// [
//   { path: "theme", type: "changed", oldValue: "light", newValue: "dark" },
//   { path: "lang", type: "added", newValue: "en" },
// ]

Nested objects are walked recursively and paths are dot-separated:

const changes = configDiff(
  { database: { host: "localhost", port: 5432 } },
  { database: { host: "db.example.com", port: 5432 } },
);
// [
//   { path: "database.host", type: "changed", oldValue: "localhost", newValue: "db.example.com" },
// ]

Recursion depth is capped at 64 levels. If either object contains nesting deeper than 64 levels, configDiff() throws "configDiff: maximum nesting depth exceeded". In practice, config objects are never this deep.

Using configDiff with onChange

A common pattern is to call configDiff inside an onChange listener to react only to specific fields:

import { Configurate, configDiff } from "tauri-plugin-configurate-api";

let previousData = (await config.load().run()).data;

const unlisten = await config.onChange(async () => {
  const nextData = (await config.load().run()).data;
  const changes = configDiff(
    previousData as Record<string, unknown>,
    nextData as Record<string, unknown>,
  );

  for (const change of changes) {
    if (change.path === "theme") {
      applyTheme(change.newValue as string);
    }
  }

  previousData = nextData;
});

DiffEntry

Each element in the array returned by configDiff() conforms to this interface.

interface DiffEntry {
  path: string;
  type: "added" | "removed" | "changed";
  oldValue?: unknown;
  newValue?: unknown;
}

string

Dot-separated path to the changed key, relative to the root of the config object. For example, a change to database.host produces "database.host".

"added" | "removed" | "changed"

The kind of change:

"added" — the key is present in newData but absent in oldData.
"removed" — the key is present in oldData but absent in newData.
"changed" — the key is present in both but the values differ.

unknown

The previous value. Present for "removed" and "changed" entries; absent for "added".

unknown

The new value. Present for "added" and "changed" entries; absent for "removed".

const changes = configDiff(
  { theme: "light", fontSize: 14, lang: "en" },
  { theme: "dark", fontSize: 14 },
);
// [
//   { path: "theme",  type: "changed", oldValue: "light", newValue: "dark" },
//   { path: "lang",   type: "removed", oldValue: "en" },
// ]

MigrationStep

MigrationStep is the interface you implement to define how config data should be transformed when the stored version is older than the current version declared in the Configurate constructor. Migrations are applied automatically during load(); if any step runs, the migrated result is auto-saved back to storage.

interface MigrationStep<
  TData extends Record<string, unknown> = Record<string, unknown>
> {
  version: number;
  up: (data: TData) => TData;
}

number

The schema version this step upgrades from. A step with version: 1 transforms data that was saved at version 1 into version 2.

(data: TData) => TData

A pure transform function. Receives the config data at the declared version and must return the data shaped for the next version. Do not mutate the input object — return a new one.

How versioning works

When you set version: N in the constructor, the plugin stores __configurate_version__: N alongside your data on every write. On load(), it reads the stored version and runs every MigrationStep whose version is less than the stored version, in ascending order, until the data reaches the current version.

import {
  Configurate,
  defineConfig,
  JsonProvider,
} from "tauri-plugin-configurate-api";
import { BaseDirectory } from "@tauri-apps/api/path";

const schema = defineConfig({
  theme: String,
  fontSize: Number,
  // "lang" was added in v1
  // "legacyFlag" was removed in v2
});

const config = new Configurate({
  schema,
  fileName: "app.json",
  baseDir: BaseDirectory.AppConfig,
  provider: JsonProvider(),
  version: 2,
  migrations: [
    {
      // Upgrade from version 0 → 1: add the "lang" field
      version: 0,
      up: (data) => ({ ...data, lang: "en" }),
    },
    {
      // Upgrade from version 1 → 2: remove the deprecated "legacyFlag" field
      version: 1,
      up: (data) => {
        const { legacyFlag, ...rest } = data as typeof data & { legacyFlag?: unknown };
        return rest as typeof data;
      },
    },
  ],
});

Write each up function as a pure transform — copy the input with the spread operator and add or omit fields rather than mutating in place. This makes migration logic easier to unit-test and reason about.

If a migrated config cannot be auto-saved back (for example, because the disk is full), the failure is logged as a warning but does not surface to your code. The migrated data is still returned in memory for the current session.

TypeScript API

Rust API

Utility Functions: configDiff and MigrationStep Reference

configDiff(oldData, newData)

Using configDiff with onChange

DiffEntry

MigrationStep

How versioning works

​configDiff(oldData, newData)

​Using configDiff with onChange

​DiffEntry

​MigrationStep

​How versioning works

configDiff(oldData, newData)

Using configDiff with onChange

DiffEntry

MigrationStep

How versioning works