Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/harshkhandeparkar/tauri-settings

A user settings manager library for Tauri inspired by electron-settings.
https://github.com/harshkhandeparkar/tauri-settings

settings-manager tauri tauri-apps tauri-settings

Last synced: about 1 month ago
JSON representation

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

Awesome Lists containing this project

README 

        
## Tauri Settings

A user settings manager for [Tauri](https://tauri.app) inspired by [electron-settings](https://github.com/nathanbuchar/electron-settings).



### Table of Contents

- [Installation And Usage](#installation-and-usage)

- [Differences From `electron-settings`](#differences-from-electron-settings)

- [API Docs](https://harshkhandeparkar.github.io/tauri-settings/)

- [License](LICENSE)



### Installation And Usage

#### Install The Package

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

```shell

# 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.

```shell

# 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](https://tauri.app/v1/api/config/#allowlistconfig).

```jsonc

{

  "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](#standalone-functions) for quick usage or a [`SettingsManager`](#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](https://www.typescriptlang.org/docs/handbook/2/generics.html#hello-world-of-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`](#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`](#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](#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`](#settingsmanager).

Each of the following methods has an `options` parameter. See the [Config](#config) to learn more.



- `async has(key, options = {})`: Async function that resolves with a boolean which is true if the given key exists in the settings.

- `async get(key, options = {})`: Async function that resolves with the value of the setting corresponding to the given key.

- `async set(key, value, options = {})`: Async function that sets the value of a given setting. Resolves with the entire settings object.

- `async getAll(, options = {})`: Async function that resolves with the entire settings object.



Here `key` uses [dot notation](#dot-notation).



#### Examples

```ts

type Schema = {

  theme: 'dark' | 'light';

  startFullscreen: boolean;

}



get('theme').then((theme) => {

  // change the theme

})



// when the theme is changed by the user

set('theme').then(() => console.log('theme changed succesfully'));

```



See the complete [API Docs](https://harshkhandeparkar.github.io/tauri-settings/).



#### 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](#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](#dot-notation) is also supported here.



`SettingsManager` class can also be initialized with the `SettingsSchema` generic. (see [Usage](#usage))



#### Examples

```ts

// TypeScript



import { SettingsManager } from 'tauri-settings';



type Schema = {

  theme: 'dark' | 'light';

  startFullscreen: boolean;

}



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(() => {

  // 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();

```



```js

// 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](https://harshkhandeparkar.github.io/tauri-settings/).



### Differences From `electron-settings`

#### Asynchronous

Since the Tauri [`fs` API](https://tauri.app/v1/api/js/fs) 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`](#settingsmanager) can be used to synchronously set and read the settings.



#### Dot Notation

`electron-settings` allows you to access settings by using [dot notation](https://electron-settings.js.org/index.html#keypath).

`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:

```js

{

  theme: {

    mode: 'dark',

    accent: 'red'

  }

}

```

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



The following will NOT work:

```js

{

  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()`](https://electron-settings.js.org/index.html#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](https://harshkhandeparkar.github.io/tauri-settings/)).



****

#### Thank You