{"id":20434259,"url":"https://github.com/alex8088/electron-conf","last_synced_at":"2025-04-12T13:41:51.863Z","repository":{"id":240842418,"uuid":"803289246","full_name":"alex8088/electron-conf","owner":"alex8088","description":"Simple data persistence for your Electron app - save and load user settings, app state, cache, etc","archived":false,"fork":false,"pushed_at":"2025-03-16T14:50:32.000Z","size":129,"stargazers_count":58,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-26T08:22:20.829Z","etag":null,"topics":["config","electron","electron-store","persistence","preferences","settings","storage","store"],"latest_commit_sha":null,"homepage":"","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/alex8088.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"publiccode":null,"codemeta":null}},"created_at":"2024-05-20T12:47:32.000Z","updated_at":"2025-03-16T14:50:06.000Z","dependencies_parsed_at":"2024-08-21T15:25:05.332Z","dependency_job_id":null,"html_url":"https://github.com/alex8088/electron-conf","commit_stats":null,"previous_names":["alex8088/electron-conf"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex8088%2Felectron-conf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex8088%2Felectron-conf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex8088%2Felectron-conf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex8088%2Felectron-conf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alex8088","download_url":"https://codeload.github.com/alex8088/electron-conf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248574518,"owners_count":21127031,"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":["config","electron","electron-store","persistence","preferences","settings","storage","store"],"created_at":"2024-11-15T08:25:32.944Z","updated_at":"2025-04-12T13:41:51.833Z","avatar_url":"https://github.com/alex8088.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# electron-conf\n\n\u003e Simple data persistence for your Electron app - save and load user settings, app state, cache, etc\n\n\u003e Another electron-store, minimal fork of conf, with more features.\n\nelectron-conf is a fork of [conf](https://github.com/sindresorhus/conf) (behind [electron-store](https://github.com/sindresorhus/electron-store)). What we try to achieve in this library, is to eliminate some dependencies and features that our target users don't need, and is designed only for Electron.\n\n- ✅ Minimal and simple\n- ✅ Read data form disk once, ~100x faster\n- ✅ Simpler migration strategy\n- ✅ Safer to use it in Electron renderer (no nodeIntegration)\n- ✅ Written in TypeScript, and support CommonJS and ESM. For Electron 15.x and higher.\n- ❌ No watch\n- ❌ No encryption\n\n_If you need features like watch or encryption, electron-store is a better choice for you._\n\n## Install\n\n```sh\n$ npm install electron-conf\n```\n\n## Usage\n\n### Using in Electron Main Process\n\n```ts\nimport { Conf } from 'electron-conf/main'\n\nconst conf = new Conf()\n\nconf.set('foo', '🌈')\nconsole.log(conf.get('foo')) // =\u003e 🌈\n\n// Use dot-notation to access nested properties\nconf.set('a.b', true)\nconsole.log(conf.get('a')) // =\u003e {b: true}\n\nconf.delete('foo')\nconsole.log(conf.get('foo')) // =\u003e undefined\n```\n\n### Using in Electron Renderer Process\n\n1. Register a listener in main process, so that you can use it in the renderer process.\n\n```ts\nimport { Conf } from 'electron-conf/main'\n\nconst conf = new Conf()\n\nconf.registerRendererListener()\n```\n\n2. Expose the `Conf` API.\n\nYou can expose it in the specified preload script:\n\n```ts\nimport { exposeConf } from 'electron-conf/preload'\n\nexposeConf()\n```\n\nOr, you can expose it globally in the main process for all renderer processes:\n\n```ts\nimport { useConf } from 'electron-conf/main'\n\nuseConf()\n```\n\n3. Use it in the renderer process\n\n```ts\nimport { Conf } from 'electron-conf/renderer'\n\nconst conf = new Conf()\n\nawait conf.set('foo', 1)\n```\n\n\u003e [!NOTE]\n\u003e Use the same way as the main process. The difference is that all APIs are promise-based.\n\n## API\n\n### Conf([options])\n\nreturn a new instance.\n\n\u003e [!WARNING]\n\u003e It does not support multiple instances reading and writing the same configuration file.\n\n### Constructor Options\n\n\u003e [!NOTE]\n\u003e `Conf` for the renderer process, only supports the `name` option.\n\n#### `dir`\n\n- Type: `string`\n- Default: [`app.getPath('userData')`](https://www.electronjs.org/docs/latest/api/app#appgetpathname)\n\nThe directory for storing your app's configuration file.\n\n#### `name`\n\n- Type: `string`\n- Default: `config`\n\nConfiguration file name without extension.\n\n#### `ext`\n\n- Type: `string`\n- Default: `.json`\n\nConfiguration file extension.\n\n#### `defaults`\n\n- Type: `object`\n\nDefault config used if there are no existing config.\n\n#### `serializer`\n\n- Type: [`Serializer`](./src/types.ts)\n\nProvides functionality to serialize object types to UTF-8 strings and to deserialize UTF-8 strings into object types.\n\nBy default, `JSON.stringify` is used for serialization and `JSON.parse` is used for deserialization.\n\nYou would usually not need this, but it could be useful if you want to use a format other than JSON.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eType Signature\u003c/b\u003e\u003c/summary\u003e\n\u003cp\u003e\u003c/p\u003e\n\n```ts\ninterface Serializer\u003cT\u003e {\n  /**\n   * Deserialize the config object from a UTF-8 string when reading the config file.\n   * @param raw UTF-8 encoded string.\n   */\n  read: (raw: string) =\u003e T\n  /**\n   * Serialize the config object to a UTF-8 string when writing the config file.\n   * @param value The config object.\n   */\n  write: (value: T) =\u003e string\n}\n```\n\n\u003c/details\u003e\n\n#### `schema`\n\n- Type: [JSONSchema](https://json-schema.org/understanding-json-schema/reference/object#properties)\n\n[JSON Schema](https://json-schema.org) to validate your config data.\n\nUnder the hood, we use the [ajv](https://ajv.js.org/) JSON Schema validator to validate config data.\n\nYou should define your schema as an object where each key is the name of your data's property and each value is a JSON schema used to validate that property.\n\n```ts\nimport { Conf } from 'electron-conf/main'\n\nconst schema = {\n  type: 'object',\n  properties: {\n    foo: {\n      type: 'string',\n      maxLength: 10,\n      nullable: true\n    }\n  }\n}\n\nconst conf = new Conf({ schema })\n```\n\n#### `migrations`\n\n- type: [`Migration[]`](./src/types.ts)\n\nYou can customize versions and perform operations to migrate configurations. When instantiated, it will be compared with the version number of the configuration file and a higher version migration operation will be performed.\n\n**Note:** The migration version must be greater than `0`. A new version is defined on each migration and is incremented on the previous version.\n\n```ts\nimport { Conf } from 'electron-conf/main'\n\nconst migrations = [\n  {\n    version: 1,\n    hook: (conf, version): void =\u003e {\n      conf.set('foo', 'a')\n      console.log(`migrate from ${version} to 1`) // migrate from 0 to 1\n    }\n  },\n  {\n    version: 2,\n    hook: (conf, version): void =\u003e {\n      conf.set('foo', 'b')\n      console.log(`migrate from ${version} to 2`) // migrate from 1 to 2\n    }\n  }\n]\n\nconst conf = new Conf({ migrations })\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eType Signature\u003c/b\u003e\u003c/summary\u003e\n\u003cp\u003e\u003c/p\u003e\n\n```ts\ntype Migration\u003cT extends Record\u003cstring, any\u003e\u003e = {\n  /**\n   * Migration version. The initial version must be greater than `0`. A new\n   * version is defined on each migration and is incremented on the previous version.\n   */\n  version: number\n  /**\n   * Migration hook. You can perform operations to update your configuration.\n   * @param instance config instance.\n   * @param currentVersion current version.\n   */\n  hook: (instance: BaseConf\u003cT\u003e, currentVersion: number) =\u003e void\n}\n```\n\n\u003c/details\u003e\n\u003cp\u003e\u003c/p\u003e\n\n### Instance Methods\n\nYou can use [dot-notation](https://github.com/sindresorhus/dot-prop) in a key to access nested properties.\n\nThe instance is [`iterable`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Iteration_protocols) so you can use it directly in a [`for…of`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Statements/for...of) loop.\n\n\u003e [!NOTE]\n\u003e All methods in renderer are promise-based.\n\n#### `.get(key, defaultValue?)`\n\nGet an item or defaultValue if the item does not exist.\n\n#### `.set(key, value)`\n\nSet an item.\n\n#### `.set(object)`\n\nSet an item or multiple items at once.\n\n```js\nconf.set({ foo: 'boo', bar: { baz: 1 } })\n```\n\n#### `.reset(...keys)`\n\nReset items to their default values, as defined by the defaults or schema option.\n\n#### `.has(key)`\n\nCheck if an item exists.\n\n#### `.delete(key)`\n\nDelete an item.\n\n#### `.clear()`\n\nDelete all items.\n\n#### `.onDidChange(key, callback)`\n\n- `callback`: `(newValue, oldValue) =\u003e {}`\n\nWatches the given `key`, calling `callback` on any changes.\n\nWhen a key is first set `oldValue` will be `undefined`, and when a key is deleted `newValue` will be `undefined`.\n\nReturns a function which you can use to unsubscribe:\n\n```js\nconst unsubscribe = conf.onDidChange(key, callback)\n\nunsubscribe()\n```\n\n\u003e [!TIP]\n\u003e Not available in renderer\n\n#### `.onDidAnyChange(callback)`\n\n- `callback`: `(newValue, oldValue) =\u003e {}`\n\nWatches the whole config object, calling `callback` on any changes.\n\n`oldValue` and `newValue` will be the config object before and after the change, respectively. You must compare `oldValue` to `newValue `to find out what changed.\n\nReturns a function which you can use to unsubscribe:\n\n```js\nconst unsubscribe = store.onDidAnyChange(callback)\n\nunsubscribe()\n```\n\n\u003e [!TIP]\n\u003e Not available in renderer\n\n#### `.fileName`\n\nGet the configuration file path.\n\n\u003e [!TIP]\n\u003e Not available in renderer\n\n## Credits\n\n[Conf](https://github.com/sindresorhus/conf), simple config handling for your app or module.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falex8088%2Felectron-conf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falex8088%2Felectron-conf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falex8088%2Felectron-conf/lists"}