# electron-json-storage-alt

> Easily write and read user settings in Electron apps

Latest version **34.0.2** (published 2025-10-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install electron-json-storage-alt
pnpm add electron-json-storage-alt
yarn add electron-json-storage-alt
bun add electron-json-storage-alt
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 34.0.2 |
| Published | 2025-10-29 |
| First published | 2020-03-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 96.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Juan Cruz Viotti |
| Maintainers | xudafeng, wynterding |
| Keywords | electron, json, storage, user, app, data |

## Links

- npm: https://www.npmjs.com/package/electron-json-storage-alt
- Repository: https://github.com/electron-modules/electron-json-storage-alt
- Issues: https://github.com/electron-modules/electron-json-storage-alt/issues
- npm.io page: https://npm.io/package/electron-json-storage-alt

## Dependencies (6)

- [async](https://npm.io/package/async.md) ^2.0.0
- [lodash](https://npm.io/package/lodash.md) 4
- [mkdirp](https://npm.io/package/mkdirp.md) 1.0.4
- [rimraf](https://npm.io/package/rimraf.md) 2
- [lockfile](https://npm.io/package/lockfile.md) ^1.0.4
- [write-file-atomic](https://npm.io/package/write-file-atomic.md) ^2.4.2

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 34.0.2 (latest) — 2025-10-29
- 34.0.1 — 2025-10-29
- 34.0.0 — 2025-05-27
- 18.2.1 — 2023-03-21
- 18.2.0 — 2023-03-21
- 18.1.0 — 2023-03-02
- 18.0.0 — 2022-05-15
- 17.0.1 — 2022-03-31
- 17.0.0 — 2022-03-31
- 13.0.0 — 2021-12-08
- 0.1.0 — 2020-03-15

## README

electron-json-storage
=====================

> Easily write and read user settings in Electron apps

[![npm version](https://badge.fury.io/js/electron-json-storage.svg)](http://badge.fury.io/js/electron-json-storage)
[![dependencies](https://david-dm.org/jviotti/electron-json-storage.svg)](https://david-dm.org/jviotti/electron-json-storage.svg)
[![Build Status](https://travis-ci.org/electron-userland/electron-json-storage.svg?branch=master)](https://travis-ci.org/electron-userland/electron-json-storage)
[![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)

[Electron](http://electron.atom.io) lacks an easy way to persist and read user settings for your application. `electron-json-storage` implements an API somehow 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')`.

Related modules:

- [electron-settings](https://github.com/nathanbuchar/electron-settings)
- [electron-store](https://github.com/sindresorhus/electron-store)
- [electron-storage](https://github.com/Cocycles/electron-storage)

Installation
------------

Install `electron-json-storage` by running:

```sh
$ npm install --save electron-json-storage
```

You can require this module from only the **main** process (`remote` module is deprecated after Electron 12).

Use in renderer process
------------

set `preload.js` as preload file of `BrowserWindow`/`webview`

```js
'use strict';

const storage = require('electron-json-storage-alt');
const { promisify } = require('util');
const { ipcRenderer, contextBridge } = require('electron');

contextBridge.exposeInMainWorld(
  '_electron_bridge',
  {
    storage: {
      get: promisify(storage.get),
      set: promisify(storage.set),
    },
  }
);
```

get `storage` from `contextBridge`:

```js
const saveToStorage = async () => {
  await window._electron_bridge.storage.set('test_storage_current_time', new Date());
  const time = await window._electron_bridge.storage.get('test_storage_current_time');
  console.log('test_storage_current_time', time);
}
```

Documentation
-------------


* [storage](#module_storage)
    * [.getDefaultDataPath()](#module_storage.getDefaultDataPath) ⇒ <code>String</code>
    * [.setDataPath(directory)](#module_storage.setDataPath)
    * [.getDataPath()](#module_storage.getDataPath) ⇒ <code>String</code>
    * [.get(key, [options], callback)](#module_storage.get)
    * [.getMany(keys, [options], callback)](#module_storage.getMany)
    * [.getAll([options], callback)](#module_storage.getAll)
    * [.set(key, json, [options], callback)](#module_storage.set)
    * [.has(key, [options], callback)](#module_storage.has)
    * [.keys([options], callback)](#module_storage.keys)
    * [.remove(key, [options], callback)](#module_storage.remove)
    * [.clear([options], callback)](#module_storage.clear)

<a name="module_storage.getDefaultDataPath"></a>

### storage.getDefaultDataPath() ⇒ <code>String</code>
**Kind**: static method of <code>[storage](#module_storage)</code>  
**Summary**: Get the default data path  
**Returns**: <code>String</code> - default data path  
**Access:** public  
**Example**  
```js
const defaultDataPath = storage.getDefaultDataPath()
```
<a name="module_storage.setDataPath"></a>

### storage.setDataPath(directory)
The default value will be used if the directory is undefined.

**Kind**: static method of <code>[storage](#module_storage)</code>  
**Summary**: Set current data path  
**Access:** public  

| Param | Type | Description |
| --- | --- | --- |
| directory | <code>String</code> &#124; <code>Undefined</code> | directory |

**Example**  
```js
const os = require('os');
const storage = require('electron-json-storage');

storage.setDataPath(os.tmpdir());
```
<a name="module_storage.getDataPath"></a>

### storage.getDataPath() ⇒ <code>String</code>
Returns the current data path. It defaults to a directory called
"storage" inside Electron's `userData` path.

**Kind**: static method of <code>[storage](#module_storage)</code>  
**Summary**: Get current user data path  
**Returns**: <code>String</code> - the user data path  
**Access:** public  
**Example**  
```js
const storage = require('electron-json-storage');

const dataPath = storage.getDataPath();
console.log(dataPath);
```
<a name="module_storage.get"></a>

### storage.get(key, [options], callback)
If the key doesn't exist in the user data, an empty object is returned.
Also notice that the `.json` extension is added automatically, but it's
ignored if you pass it yourself.

Passing an extension other than `.json` will result in a file created
with both extensions. For example, the key `foo.data` will result in a file
called `foo.data.json`.

**Kind**: static method of <code>[storage](#module_storage)</code>  
**Summary**: Read user data  
**Access:** public  

| Param | Type | Description |
| --- | --- | --- |
| key | <code>String</code> | key |
| [options] | <code>Object</code> | options |
| [options.dataPath] | <code>String</code> | data path |
| callback | <code>function</code> | callback (error, data) |

**Example**  
```js
const storage = require('electron-json-storage');

storage.get('foobar', function(error, data) {
  if (error) throw error;

  console.log(data);
});
```
<a name="module_storage.getMany"></a>

### storage.getMany(keys, [options], callback)
This function returns an object with the data of all the passed keys.
If one of the keys doesn't exist, an empty object is returned for it.

**Kind**: static method of <code>[storage](#module_storage)</code>  
**Summary**: Read many user data keys  
**Access:** public  

| Param | Type | Description |
| --- | --- | --- |
| keys | <code>Array.&lt;String&gt;</code> | keys |
| [options] | <code>Object</code> | options |
| [options.dataPath] | <code>String</code> | data path |
| callback | <code>function</code> | callback (error, data) |

**Example**  
```js
const storage = require('electron-json-storage');

storage.getMany([ 'foobar', 'barbaz' ], function(error, data) {
  if (error) throw error;

  console.log(data.foobar);
  console.log(data.barbaz);
});
```
<a name="module_storage.getAll"></a>

### storage.getAll([options], callback)
This function returns an empty object if there is no data to be read.

**Kind**: static method of <code>[storage](#module_storage)</code>  
**Summary**: Read all user data  
**Access:** public  

| Param | Type | Description |
| --- | --- | --- |
| [options] | <code>Object</code> | options |
| [options.dataPath] | <code>String</code> | data path |
| callback | <code>function</code> | callback (error, data) |

**Example**  
```js
const storage = require('electron-json-storage');

storage.getAll(function(error, data) {
  if (error) throw error;

  console.log(data);
});
```
<a name="module_storage.set"></a>

### storage.set(key, json, [options], callback)
**Kind**: static method of <code>[storage](#module_storage)</code>  
**Summary**: Write user data  
**Access:** public  

| Param | Type | Description |
| --- | --- | --- |
| key | <code>String</code> | key |
| json | <code>Object</code> | json object |
| [options] | <code>Object</code> | options |
| [options.dataPath] | <code>String</code> | data path |
| callback | <code>function</code> | callback (error) |

**Example**  
```js
const storage = require('electron-json-storage');

storage.set('foobar', { foo: 'bar' }, function(error) {
  if (error) throw error;
});
```
<a name="module_storage.has"></a>

### storage.has(key, [options], callback)
**Kind**: static method of <code>[storage](#module_storage)</code>  
**Summary**: Check if a key exists  
**Access:** public  

| Param | Type | Description |
| --- | --- | --- |
| key | <code>String</code> | key |
| [options] | <code>Object</code> | options |
| [options.dataPath] | <code>String</code> | data path |
| callback | <code>function</code> | callback (error, hasKey) |

**Example**  
```js
const storage = require('electron-json-storage');

storage.has('foobar', function(error, hasKey) {
  if (error) throw error;

  if (hasKey) {
    console.log('There is data stored as `foobar`');
  }
});
```
<a name="module_storage.keys"></a>

### storage.keys([options], callback)
**Kind**: static method of <code>[storage](#module_storage)</code>  
**Summary**: Get the list of saved keys  
**Access:** public  

| Param | Type | Description |
| --- | --- | --- |
| [options] | <code>Object</code> | options |
| [options.dataPath] | <code>String</code> | data path |
| callback | <code>function</code> | callback (error, keys) |

**Example**  
```js
const storage = require('electron-json-storage');

storage.keys(function(error, keys) {
  if (error) throw error;

  for (var key of keys) {
    console.log('There is a key called: ' + key);
  }
});
```
<a name="module_storage.remove"></a>

### storage.remove(key, [options], callback)
Notice this function does nothing, nor throws any error
if the key doesn't exist.

**Kind**: static method of <code>[storage](#module_storage)</code>  
**Summary**: Remove a key  
**Access:** public  

| Param | Type | Description |
| --- | --- | --- |
| key | <code>String</code> | key |
| [options] | <code>Object</code> | options |
| [options.dataPath] | <code>String</code> | data path |
| callback | <code>function</code> | callback (error) |

**Example**  
```js
const storage = require('electron-json-storage');

storage.remove('foobar', function(error) {
  if (error) throw error;
});
```
<a name="module_storage.clear"></a>

### storage.clear([options], callback)
**Kind**: static method of <code>[storage](#module_storage)</code>  
**Summary**: Clear all stored data in the current user data path  
**Access:** public  

| Param | Type | Description |
| --- | --- | --- |
| [options] | <code>Object</code> | options |
| [options.dataPath] | <code>String</code> | data path |
| callback | <code>function</code> | callback (error) |

**Example**  
```js
const storage = require('electron-json-storage');

storage.clear(function(error) {
  if (error) throw error;
});
```

Support
-------

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

Tests
-----

Run the test suite by doing:

```sh
$ npm test
```

Contribute
----------

- Issue Tracker: [github.com/electron-userland/electron-json-storage/issues](https://github.com/electron-userland/electron-json-storage/issues)
- Source Code: [github.com/electron-userland/electron-json-storage](https://github.com/electron-userland/electron-json-storage)

Before submitting a PR, please make sure that you include tests, and that [jshint](http://jshint.com) runs without any warning:

```sh
$ npm run-script lint
```

License
-------

The project is licensed under the MIT license.

---
_Source: https://npm.io/package/electron-json-storage-alt · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._