{"id":15231947,"url":"https://github.com/harshkhandeparkar/tauri-settings","last_synced_at":"2025-08-20T22:32:22.470Z","repository":{"id":63249376,"uuid":"389191124","full_name":"harshkhandeparkar/tauri-settings","owner":"harshkhandeparkar","description":"A user settings manager library for Tauri inspired by electron-settings.","archived":false,"fork":false,"pushed_at":"2024-04-13T14:08:43.000Z","size":491,"stargazers_count":70,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-04-14T04:07:15.547Z","etag":null,"topics":["settings-manager","tauri","tauri-apps","tauri-settings"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/tauri-settings","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/harshkhandeparkar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-07-24T20:06:02.000Z","updated_at":"2024-04-23T21:38:39.778Z","dependencies_parsed_at":"2024-04-13T15:28:13.277Z","dependency_job_id":null,"html_url":"https://github.com/harshkhandeparkar/tauri-settings","commit_stats":{"total_commits":62,"total_committers":5,"mean_commits":12.4,"dds":"0.16129032258064513","last_synced_commit":"d7fb43ac77f1a9e62d6c8679b18fa48717a8f2cd"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harshkhandeparkar%2Ftauri-settings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harshkhandeparkar%2Ftauri-settings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harshkhandeparkar%2Ftauri-settings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harshkhandeparkar%2Ftauri-settings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/harshkhandeparkar","download_url":"https://codeload.github.com/harshkhandeparkar/tauri-settings/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230462907,"owners_count":18229864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["settings-manager","tauri","tauri-apps","tauri-settings"],"created_at":"2024-09-29T04:06:22.753Z","updated_at":"2024-12-19T16:12:29.936Z","avatar_url":"https://github.com/harshkhandeparkar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Tauri Settings\nA user settings manager for [Tauri](https://tauri.app) inspired by [electron-settings](https://github.com/nathanbuchar/electron-settings).\n\n### Table of Contents\n- [Installation And Usage](#installation-and-usage)\n- [Differences From `electron-settings`](#differences-from-electron-settings)\n- [API Docs](https://harshkhandeparkar.github.io/tauri-settings/)\n- [License](LICENSE)\n\n### Installation And Usage\n#### Install The Package\nThe package is available on npm and can be installed using npm or yarn.\n```shell\n# using npm\nnpm install tauri-settings\n\n# using yarn\nyarn add tauri-settings\n\n# using pnpm\npnpm add tauri-settings\n```\n\n#### Install The Tauri API\nIf 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.\n```shell\n# using npm\nnpm install @tauri-apps/api\n\n# using yarn\nyarn add @tauri-apps/api\n```\n\n#### Enable Tauri APIs\nThe following APIs need to be added to the Tauri [allowlist](https://tauri.app/v1/api/config/#allowlistconfig).\n```jsonc\n{\n  \"allowlist\": {\n    \"fs\": { // see https://tauri.app/v1/api/config/#fsallowlistconfig\n      \"createDir\": true,\n      \"readDir\": true,\n      \"readFile\": true,\n      \"writeFile\": true,\n      \"scope\": [\"$APPCONFIG\", \"$APPCONFIG/*\"]\n    },\n    \"path\": {\n      \"all\": true\n     }\n  }\n}\n```\n\n#### Usage\n`tauri-settings` exports a set of [standalone functions](#standalone-functions) for quick usage or a [`SettingsManager`](#settingsmanager) class with extra features such as caching.\nTypescript typings and JSDoc is provided for all the API methods.\n\nThe 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.\nIt is highly recommended to use a defined schema to prevent runtime errors.\n\n[`SettingsManager`](#settingsmanager) class can also be initialized with a `SettingsSchema` generic. This generic will be used by all the methods of the class instance.\nApart 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).\n\nUsing 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.\n\n#### Standalone Functions\n`tauri-settings` exports the following API methods to directly set or get settings for quick usage. Alternatively you can also use [`SettingsManager`](#settingsmanager).\nEach of the following methods has an `options` parameter. See the [Config](#config) to learn more.\n\n- `async has\u003cSettingsSchema\u003e(key, options = {})`: Async function that resolves with a boolean which is true if the given key exists in the settings.\n- `async get\u003cSettingsSchema\u003e(key, options = {})`: Async function that resolves with the value of the setting corresponding to the given key.\n- `async set\u003cSettingsSchema\u003e(key, value, options = {})`: Async function that sets the value of a given setting. Resolves with the entire settings object.\n- `async getAll\u003cSettingsSchema\u003e(, options = {})`: Async function that resolves with the entire settings object.\n\nHere `key` uses [dot notation](#dot-notation).\n\n#### Examples\n```ts\ntype Schema = {\n  theme: 'dark' | 'light';\n  startFullscreen: boolean;\n}\n\nget\u003cSchema\u003e('theme').then((theme) =\u003e {\n  // change the theme\n})\n\n// when the theme is changed by the user\nset\u003cSchema\u003e('theme').then(() =\u003e console.log('theme changed succesfully'));\n```\n\nSee the complete [API Docs](https://harshkhandeparkar.github.io/tauri-settings/).\n\n#### SettingsManager\n`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*.\nIt provides additional features such as caching the settings in the memory, setting defaults and in the future, listening to changes in the settings.\n\nThe 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:\n- Quick access without making filesystem changes\n- Updating settings in batch\n- Using the API syncrhonously (See [Differences From `electron-settings`: Asynchronous](#asynchronous))\n- Deferring the filesystem events to a more convenient time\n\nThe cached settings can be accessed by using the `hasCache`, `getCache` or `setCache` methods.\nThe 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.\n\n[Dot notation](#dot-notation) is also supported here.\n\n`SettingsManager` class can also be initialized with the `SettingsSchema` generic. (see [Usage](#usage))\n\n#### Examples\n```ts\n// TypeScript\n\nimport { SettingsManager } from 'tauri-settings';\n\ntype Schema = {\n  theme: 'dark' | 'light';\n  startFullscreen: boolean;\n}\n\nconst settingsManager = new SettingsManager\u003cSchema\u003e(\n  { // defaults\n    theme: 'light',\n    startFullscreen: false\n  },\n  { // options\n    fileName: 'customization-settings'\n  }\n)\n\n// checks whether the settings file exists and created it if not\n// loads the settings if it exists\nsettingsManager.initialize().then(() =\u003e {\n  // any key other than 'theme' and 'startFullscreen' will be invalid.\n  // theme key will only accept 'dark' or 'light' as a value due to the generic.\n  settingsManager.setCache('theme', 'dark');\n}\n\n// at a later time\nawait settingsManager.syncCache();\n```\n\n```js\n// JavaScript\n\nimport { SettingsManager } from 'tauri-settings';\n\nconst settingsManager = new SettingsManager(\n  { // defaults\n    theme: 'light',\n    startFullscreen: false\n  },\n  { // options\n    fileName: 'customization-settings'\n  }\n);\n\n// checks whether the settings file exists and created it if not\n// loads the settings if it exists\nsettingsManager.initialize().then(() =\u003e {\n  // there is no schema, so any key will be accepted\n  // the user needs to add their own validation scheme\n  settingsManager.setCache('theme', 'dark');\n}\n\n// at a later time\nawait settingsManager.syncCache();\n\n```\n\nSee the complete [API Docs](https://harshkhandeparkar.github.io/tauri-settings/).\n\n### Differences From `electron-settings`\n#### Asynchronous\nSince 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.\n\nEven though synchronous `fs` API is not available, the caching feature of [`SettingsManager`](#settingsmanager) can be used to synchronously set and read the settings.\n\n#### Dot Notation\n`electron-settings` allows you to access settings by using [dot notation](https://electron-settings.js.org/index.html#keypath).\n`tauri-settings` supports (Thanks to https://github.com/harshkhandeparkar/tauri-settings/pull/3) the above feature without the array notation `key.array[4]`.\n\nExample:\nIf the settings schema looks like this:\n```js\n{\n  theme: {\n    mode: 'dark',\n    accent: 'red'\n  }\n}\n```\n`get('theme.mode')` will return `dark`.\n\nThe following will NOT work:\n```js\n{\n  search: {\n    recents: ['keyword1', 'keyword2', 'keyword3']\n  }\n}\n```\n`get('search.recents[3]')` will return `null` whereas `get('search.recents')` will return the entire `recents` array.\n\n#### Config\n`electron-settings` exports a [`configure()`](https://electron-settings.js.org/index.html#configure) method to configure some of the options such as the fileName.\nHowever, `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/)).\n\n****\n#### Thank You\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharshkhandeparkar%2Ftauri-settings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharshkhandeparkar%2Ftauri-settings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharshkhandeparkar%2Ftauri-settings/lists"}