Tauri Settings

A user settings manager for Tauri inspired by electron-settings.

Table of Contents

• Installation And Usage
• Differences From electron-settings
• API Docs
• License

Installation And Usage

Install The Package

The package is available on npm and can be installed using npm or yarn.

# using npm
npm install tauri-settings

# using yarn
yarn add tauri-settings

# using pnpm
pnpm add tauri-settings

Install The Tauri API

If you haven't installed @tauri-apps/api then you will have to install it using npm or yarn as this package internally uses the API.

# using npm
npm install @tauri-apps/api

# using yarn
yarn add @tauri-apps/api

Enable Tauri APIs

The following APIs need to be added to the Tauri allowlist.

{
  "allowlist": {
    "fs": { // see https://tauri.app/v1/api/config/#fsallowlistconfig
      "createDir": true,
      "readDir": true,
      "readFile": true,
      "writeFile": true,
      "scope": ["$APPCONFIG", "$APPCONFIG/*"]
    },
    "path": {
      "all": true
     }
  }
}

Usage

tauri-settings exports a set of standalone functions for quick usage or a SettingsManager class with extra features such as caching. Typescript typings and JSDoc is provided for all the API methods.

The API also uses typescript generics to allow a defined schema to be used. In the following sections, SettingsSchema is an optional generic type for the settings schema. It is highly recommended to use a defined schema to prevent runtime errors.

SettingsManager class can also be initialized with a SettingsSchema generic. This generic will be used by all the methods of the class instance. Apart from basic setters and getters, the SettingsManager class also caches the value of the settings in the memory for quick access. This can also be used to make the api calls synchronous. See Differences From electron-settings: Asynchronous.

Using both the standalone methods and SettingsManager together can cause unexpected behaviour. If a setting is accessed both by the frontend and the backend then not using the caching feature is recommended.

Standalone Functions

tauri-settings exports the following API methods to directly set or get settings for quick usage. Alternatively you can also use SettingsManager. Each of the following methods has an options parameter. See the Config to learn more.

• async has<SettingsSchema>(key, options = {}): Async function that resolves with a boolean which is true if the given key exists in the settings.
• async get<SettingsSchema>(key, options = {}): Async function that resolves with the value of the setting corresponding to the given key.
• async set<SettingsSchema>(key, value, options = {}): Async function that sets the value of a given setting. Resolves with the entire settings object.
• async getAll<SettingsSchema>(, options = {}): Async function that resolves with the entire settings object.

Here key uses dot notation.

Examples

type Schema = {
  theme: 'dark' | 'light';
  startFullscreen: boolean;
}

get<Schema>('theme').then((theme) => {
  // change the theme
})

// when the theme is changed by the user
set<Schema>('theme').then(() => console.log('theme changed succesfully'));

See the complete API Docs.

SettingsManager

SettingsManager is a class that can be used not only to set and get settings but it is meant to be a complete settings manager. It provides additional features such as caching the settings in the memory, setting defaults and in the future, listening to changes in the settings.

The caching feature stores a copy of the settings on the RAM and does not directly alter the settings file on persistent storage. This can be useful in multiple cases:

• Quick access without making filesystem changes
• Updating settings in batch
• Using the API syncrhonously (See Differences From electron-settings: Asynchronous)
• Deferring the filesystem events to a more convenient time

The cached settings can be accessed by using the hasCache, getCache or setCache methods. The cache can be synced (written to persistent storage) at any time or the persistent storage can be accessed at any time using the has, get and set methods.

Dot notation is also supported here.

SettingsManager class can also be initialized with the SettingsSchema generic. (see Usage)

Examples

// TypeScript

import { SettingsManager } from 'tauri-settings';

type Schema = {
  theme: 'dark' | 'light';
  startFullscreen: boolean;
}

const settingsManager = new SettingsManager<Schema>(
  { // defaults
    theme: 'light',
    startFullscreen: false
  },
  { // options
    fileName: 'customization-settings'
  }
)

// checks whether the settings file exists and created it if not
// loads the settings if it exists
settingsManager.initialize().then(() => {
  // any key other than 'theme' and 'startFullscreen' will be invalid.
  // theme key will only accept 'dark' or 'light' as a value due to the generic.
  settingsManager.setCache('theme', 'dark');
}

// at a later time
await settingsManager.syncCache();

// JavaScript

import { SettingsManager } from 'tauri-settings';

const settingsManager = new SettingsManager(
  { // defaults
    theme: 'light',
    startFullscreen: false
  },
  { // options
    fileName: 'customization-settings'
  }
);

// checks whether the settings file exists and created it if not
// loads the settings if it exists
settingsManager.initialize().then(() => {
  // there is no schema, so any key will be accepted
  // the user needs to add their own validation scheme
  settingsManager.setCache('theme', 'dark');
}

// at a later time
await settingsManager.syncCache();

See the complete API Docs.

Differences From electron-settings

Asynchronous

Since the Tauri fs API is asynchronous, the API methods exported by tauri-settings are also asynchronous. Methods setSync, getSync, and hasSync from electron-settings are not available.

Even though synchronous fs API is not available, the caching feature of SettingsManager can be used to synchronously set and read the settings.

Dot Notation

electron-settings allows you to access settings by using dot notation. tauri-settings supports (Thanks to https://github.com/harshkhandeparkar/tauri-settings/pull/3) the above feature without the array notation key.array[4].

Example: If the settings schema looks like this:

{
  theme: {
    mode: 'dark',
    accent: 'red'
  }
}

get('theme.mode') will return dark.

The following will NOT work:

{
  search: {
    recents: ['keyword1', 'keyword2', 'keyword3']
  }
}

get('search.recents[3]') will return null whereas get('search.recents') will return the entire recents array.

Config

electron-settings exports a configure() method to configure some of the options such as the fileName. However, tauri-settings doesn't export such a variable due to various reasons. Instead each API method such as get and set, as well as the SettingsManager class have an optional options parameter (See API Docs).

Thank You