{"id":13468777,"url":"https://github.com/electron-userland/electron-json-storage","last_synced_at":"2025-05-14T10:07:55.500Z","repository":{"id":3639742,"uuid":"50390586","full_name":"electron-userland/electron-json-storage","owner":"electron-userland","description":":package: Easily write and read user settings in Electron apps","archived":false,"fork":false,"pushed_at":"2023-06-12T15:26:15.000Z","size":697,"stargazers_count":1441,"open_issues_count":42,"forks_count":81,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-05-06T06:48:27.793Z","etag":null,"topics":["electron","json","settings","storage"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/electron-userland.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-01-26T00:15:27.000Z","updated_at":"2025-04-28T18:28:10.000Z","dependencies_parsed_at":"2023-02-18T05:45:17.403Z","dependency_job_id":null,"html_url":"https://github.com/electron-userland/electron-json-storage","commit_stats":{"total_commits":126,"total_committers":14,"mean_commits":9.0,"dds":0.5793650793650793,"last_synced_commit":"034b58beb26909cb56b98c13791b634494551f3a"},"previous_names":["jviotti/electron-json-storage"],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electron-userland%2Felectron-json-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electron-userland%2Felectron-json-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electron-userland%2Felectron-json-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electron-userland%2Felectron-json-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/electron-userland","download_url":"https://codeload.github.com/electron-userland/electron-json-storage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253214593,"owners_count":21872503,"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":["electron","json","settings","storage"],"created_at":"2024-07-31T15:01:18.885Z","updated_at":"2025-05-14T10:07:55.445Z","avatar_url":"https://github.com/electron-userland.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"electron-json-storage\n=====================\n\n\u003e Easily write and read user settings in Electron apps\n\n[![npm version](https://badge.fury.io/js/electron-json-storage.svg)](http://badge.fury.io/js/electron-json-storage)\n[![dependencies](https://david-dm.org/jviotti/electron-json-storage.svg)](https://david-dm.org/jviotti/electron-json-storage.svg)\n[![Build Status](https://travis-ci.org/electron-userland/electron-json-storage.svg?branch=master)](https://travis-ci.org/electron-userland/electron-json-storage)\n[![Build status](https://ci.appveyor.com/api/projects/status/ulwk1nnh7l8209xg/branch/master?svg=true)](https://ci.appveyor.com/project/electron-userland/electron-json-storage/branch/master)\n\n[Electron](http://electron.atom.io) lacks an easy way to persist and read user settings for your application. `electron-json-storage` implements an API somewhat similar to [localStorage](https://developer.mozilla.org/en/docs/Web/API/Window/localStorage) to write and read JSON objects to/from the operating system application data directory, as defined by `app.getPath('userData')`.\n\nRelated modules:\n\n- [electron-settings](https://github.com/nathanbuchar/electron-settings)\n- [electron-store](https://github.com/sindresorhus/electron-store)\n- [electron-storage](https://github.com/Cocycles/electron-storage)\n\nInstallation\n------------\n\nInstall `electron-json-storage` by running:\n\n```sh\n$ npm install --save electron-json-storage\n```\n\nYou can require this module from either the **main** or **renderer** process (with and without `remote`).\n\nRunning on Electron \u003e10 renderer processes\n------------------------------------------\n\nWhen loaded in renderer processes, this module will try to make use of\n`electron.remote` in order to fetch the `userData` path.\n\nElectron 10 now [defaults `enableRemoteModule` to\nfalse](https://www.electronjs.org/docs/breaking-changes#default-changed-enableremotemodule-defaults-to-false),\nwhich means that `electron-json-storage` will be able to calculate a data path by default.\n\nThe solution is to manually call `storage.setDataPath()` before reading or\nwriting any values or setting `enableRemoteModule` to `true`.\n\nDocumentation\n-------------\n\n\n* [storage](#module_storage)\n    * [.getDefaultDataPath()](#module_storage.getDefaultDataPath) ⇒ \u003ccode\u003eString\u003c/code\u003e \\| \u003ccode\u003eNull\u003c/code\u003e\n    * [.setDataPath(directory)](#module_storage.setDataPath)\n    * [.getDataPath()](#module_storage.getDataPath) ⇒ \u003ccode\u003eString\u003c/code\u003e\n    * [.get(key, [options], callback)](#module_storage.get)\n    * [.getSync(key, [options])](#module_storage.getSync)\n    * [.getMany(keys, [options], callback)](#module_storage.getMany)\n    * [.getAll([options], callback)](#module_storage.getAll)\n    * [.set(key, json, [options], callback)](#module_storage.set)\n    * [.has(key, [options], callback)](#module_storage.has)\n    * [.keys([options], callback)](#module_storage.keys)\n    * [.remove(key, [options], callback)](#module_storage.remove)\n    * [.clear([options], callback)](#module_storage.clear)\n\n\u003ca name=\"module_storage.getDefaultDataPath\"\u003e\u003c/a\u003e\n\n### storage.getDefaultDataPath() ⇒ \u003ccode\u003eString\u003c/code\u003e \\| \u003ccode\u003eNull\u003c/code\u003e\nThis function will return `null` when running in the\nrenderer process without support for the `remote` IPC\nmechanism. You have to explicitly set a data path using\n`.setDataPath()` in these cases.\n\n**Kind**: static method of [\u003ccode\u003estorage\u003c/code\u003e](#module_storage)  \n**Summary**: Get the default data path  \n**Returns**: \u003ccode\u003eString\u003c/code\u003e \\| \u003ccode\u003eNull\u003c/code\u003e - default data path  \n**Access**: public  \n**Example**  \n```js\nconst defaultDataPath = storage.getDefaultDataPath()\n```\n\u003ca name=\"module_storage.setDataPath\"\u003e\u003c/a\u003e\n\n### storage.setDataPath(directory)\nThe default value will be used if the directory is undefined.\n\n**Kind**: static method of [\u003ccode\u003estorage\u003c/code\u003e](#module_storage)  \n**Summary**: Set current data path  \n**Access**: public  \n\n| Param | Type | Description |\n| --- | --- | --- |\n| directory | \u003ccode\u003eString\u003c/code\u003e \\| \u003ccode\u003eUndefined\u003c/code\u003e | directory |\n\n**Example**  \n```js\nconst os = require('os');\nconst storage = require('electron-json-storage');\n\nstorage.setDataPath(os.tmpdir());\n```\n\u003ca name=\"module_storage.getDataPath\"\u003e\u003c/a\u003e\n\n### storage.getDataPath() ⇒ \u003ccode\u003eString\u003c/code\u003e\nReturns the current data path. It defaults to a directory called\n\"storage\" inside Electron's `userData` path.\n\n**Kind**: static method of [\u003ccode\u003estorage\u003c/code\u003e](#module_storage)  \n**Summary**: Get current user data path  \n**Returns**: \u003ccode\u003eString\u003c/code\u003e - the user data path  \n**Access**: public  \n**Example**  \n```js\nconst storage = require('electron-json-storage');\n\nconst dataPath = storage.getDataPath();\nconsole.log(dataPath);\n```\n\u003ca name=\"module_storage.get\"\u003e\u003c/a\u003e\n\n### storage.get(key, [options], callback)\nIf the key doesn't exist in the user data, an empty object is returned.\nAlso notice that the `.json` extension is added automatically, but it's\nignored if you pass it yourself.\n\nPassing an extension other than `.json` will result in a file created\nwith both extensions. For example, the key `foo.data` will result in a file\ncalled `foo.data.json`.\n\n**Kind**: static method of [\u003ccode\u003estorage\u003c/code\u003e](#module_storage)  \n**Summary**: Read user data  \n**Access**: public  \n\n| Param | Type | Description |\n| --- | --- | --- |\n| key | \u003ccode\u003eString\u003c/code\u003e | key |\n| [options] | \u003ccode\u003eObject\u003c/code\u003e | options |\n| [options.dataPath] | \u003ccode\u003eString\u003c/code\u003e | data path |\n| callback | \u003ccode\u003efunction\u003c/code\u003e | callback (error, data) |\n\n**Example**  \n```js\nconst storage = require('electron-json-storage');\n\nstorage.get('foobar', function(error, data) {\n  if (error) throw error;\n\n  console.log(data);\n});\n```\n\u003ca name=\"module_storage.getSync\"\u003e\u003c/a\u003e\n\n### storage.getSync(key, [options])\nSee `.get()`.\n\n**Kind**: static method of [\u003ccode\u003estorage\u003c/code\u003e](#module_storage)  \n**Summary**: Read user data (sync)  \n**Access**: public  \n\n| Param | Type | Description |\n| --- | --- | --- |\n| key | \u003ccode\u003eString\u003c/code\u003e | key |\n| [options] | \u003ccode\u003eObject\u003c/code\u003e | options |\n| [options.dataPath] | \u003ccode\u003eString\u003c/code\u003e | data path |\n\n**Example**  \n```js\nconst storage = require('electron-json-storage');\n\nvar data = storage.getSync('foobar');\nconsole.log(data);\n```\n\u003ca name=\"module_storage.getMany\"\u003e\u003c/a\u003e\n\n### storage.getMany(keys, [options], callback)\nThis function returns an object with the data of all the passed keys.\nIf one of the keys doesn't exist, an empty object is returned for it.\n\n**Kind**: static method of [\u003ccode\u003estorage\u003c/code\u003e](#module_storage)  \n**Summary**: Read many user data keys  \n**Access**: public  \n\n| Param | Type | Description |\n| --- | --- | --- |\n| keys | \u003ccode\u003eArray.\u0026lt;String\u0026gt;\u003c/code\u003e | keys |\n| [options] | \u003ccode\u003eObject\u003c/code\u003e | options |\n| [options.dataPath] | \u003ccode\u003eString\u003c/code\u003e | data path |\n| callback | \u003ccode\u003efunction\u003c/code\u003e | callback (error, data) |\n\n**Example**  \n```js\nconst storage = require('electron-json-storage');\n\nstorage.getMany([ 'foobar', 'barbaz' ], function(error, data) {\n  if (error) throw error;\n\n  console.log(data.foobar);\n  console.log(data.barbaz);\n});\n```\n\u003ca name=\"module_storage.getAll\"\u003e\u003c/a\u003e\n\n### storage.getAll([options], callback)\nThis function returns an empty object if there is no data to be read.\n\n**Kind**: static method of [\u003ccode\u003estorage\u003c/code\u003e](#module_storage)  \n**Summary**: Read all user data  \n**Access**: public  \n\n| Param | Type | Description |\n| --- | --- | --- |\n| [options] | \u003ccode\u003eObject\u003c/code\u003e | options |\n| [options.dataPath] | \u003ccode\u003eString\u003c/code\u003e | data path |\n| callback | \u003ccode\u003efunction\u003c/code\u003e | callback (error, data) |\n\n**Example**  \n```js\nconst storage = require('electron-json-storage');\n\nstorage.getAll(function(error, data) {\n  if (error) throw error;\n\n  console.log(data);\n});\n```\n\u003ca name=\"module_storage.set\"\u003e\u003c/a\u003e\n\n### storage.set(key, json, [options], callback)\n**Kind**: static method of [\u003ccode\u003estorage\u003c/code\u003e](#module_storage)  \n**Summary**: Write user data  \n**Access**: public  \n\n| Param | Type | Description |\n| --- | --- | --- |\n| key | \u003ccode\u003eString\u003c/code\u003e | key |\n| json | \u003ccode\u003eObject\u003c/code\u003e | json object |\n| [options] | \u003ccode\u003eObject\u003c/code\u003e | options |\n| [options.dataPath] | \u003ccode\u003eString\u003c/code\u003e | data path |\n| [options.validate] | \u003ccode\u003eString\u003c/code\u003e | validate writes by reading the data back |\n| [options.prettyPrinting] | \u003ccode\u003eboolean\u003c/code\u003e | adds line breaks and spacing to the written data |\n| callback | \u003ccode\u003efunction\u003c/code\u003e | callback (error) |\n\n**Example**  \n```js\nconst storage = require('electron-json-storage');\n\nstorage.set('foobar', { foo: 'bar' }, function(error) {\n  if (error) throw error;\n});\n```\n\u003ca name=\"module_storage.has\"\u003e\u003c/a\u003e\n\n### storage.has(key, [options], callback)\n**Kind**: static method of [\u003ccode\u003estorage\u003c/code\u003e](#module_storage)  \n**Summary**: Check if a key exists  \n**Access**: public  \n\n| Param | Type | Description |\n| --- | --- | --- |\n| key | \u003ccode\u003eString\u003c/code\u003e | key |\n| [options] | \u003ccode\u003eObject\u003c/code\u003e | options |\n| [options.dataPath] | \u003ccode\u003eString\u003c/code\u003e | data path |\n| callback | \u003ccode\u003efunction\u003c/code\u003e | callback (error, hasKey) |\n\n**Example**  \n```js\nconst storage = require('electron-json-storage');\n\nstorage.has('foobar', function(error, hasKey) {\n  if (error) throw error;\n\n  if (hasKey) {\n    console.log('There is data stored as `foobar`');\n  }\n});\n```\n\u003ca name=\"module_storage.keys\"\u003e\u003c/a\u003e\n\n### storage.keys([options], callback)\n**Kind**: static method of [\u003ccode\u003estorage\u003c/code\u003e](#module_storage)  \n**Summary**: Get the list of saved keys  \n**Access**: public  \n\n| Param | Type | Description |\n| --- | --- | --- |\n| [options] | \u003ccode\u003eObject\u003c/code\u003e | options |\n| [options.dataPath] | \u003ccode\u003eString\u003c/code\u003e | data path |\n| callback | \u003ccode\u003efunction\u003c/code\u003e | callback (error, keys) |\n\n**Example**  \n```js\nconst storage = require('electron-json-storage');\n\nstorage.keys(function(error, keys) {\n  if (error) throw error;\n\n  for (var key of keys) {\n    console.log('There is a key called: ' + key);\n  }\n});\n```\n\u003ca name=\"module_storage.remove\"\u003e\u003c/a\u003e\n\n### storage.remove(key, [options], callback)\nNotice this function does nothing, nor throws any error\nif the key doesn't exist.\n\n**Kind**: static method of [\u003ccode\u003estorage\u003c/code\u003e](#module_storage)  \n**Summary**: Remove a key  \n**Access**: public  \n\n| Param | Type | Description |\n| --- | --- | --- |\n| key | \u003ccode\u003eString\u003c/code\u003e | key |\n| [options] | \u003ccode\u003eObject\u003c/code\u003e | options |\n| [options.dataPath] | \u003ccode\u003eString\u003c/code\u003e | data path |\n| callback | \u003ccode\u003efunction\u003c/code\u003e | callback (error) |\n\n**Example**  \n```js\nconst storage = require('electron-json-storage');\n\nstorage.remove('foobar', function(error) {\n  if (error) throw error;\n});\n```\n\u003ca name=\"module_storage.clear\"\u003e\u003c/a\u003e\n\n### storage.clear([options], callback)\n**Kind**: static method of [\u003ccode\u003estorage\u003c/code\u003e](#module_storage)  \n**Summary**: Clear all stored data in the current user data path  \n**Access**: public  \n\n| Param | Type | Description |\n| --- | --- | --- |\n| [options] | \u003ccode\u003eObject\u003c/code\u003e | options |\n| [options.dataPath] | \u003ccode\u003eString\u003c/code\u003e | data path |\n| callback | \u003ccode\u003efunction\u003c/code\u003e | callback (error) |\n\n**Example**  \n```js\nconst storage = require('electron-json-storage');\n\nstorage.clear(function(error) {\n  if (error) throw error;\n});\n```\n\nSupport\n-------\n\nIf you're having any problem, please [raise an issue](https://github.com/electron-userland/electron-json-storage/issues/new) on GitHub and we'll be happy to help.\n\nTests\n-----\n\nRun the test suite by doing:\n\n```sh\n$ npm test\n```\n\nContribute\n----------\n\n- Issue Tracker: [github.com/electron-userland/electron-json-storage/issues](https://github.com/electron-userland/electron-json-storage/issues)\n- Source Code: [github.com/electron-userland/electron-json-storage](https://github.com/electron-userland/electron-json-storage)\n\nBefore submitting a PR, please make sure that you include tests, and that [jshint](http://jshint.com) runs without any warning:\n\n```sh\n$ npm run-script lint\n```\n\nLicense\n-------\n\nThe project is licensed under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felectron-userland%2Felectron-json-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felectron-userland%2Felectron-json-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felectron-userland%2Felectron-json-storage/lists"}