sindresorhus / electron-store

electron-store > Simple data persistence for your Electron app or module - Save and load user settings, app state, cache, etc Electron doesn't have a built-in way to persist user settings and other data. This module handles that for you, so you can focus on building your app. The data is saved in a JSON file named config.json in . > [!NOTE] > This is not a database. The entire JSON file is read and written on every change, so it's best suited for small data like user settings. For large data, use SQLite or similar. You can use this module directly in both the main and renderer process. For use in the renderer process only, you need to call in the main process, or create a new Store instance ( ) in the main process. Install *Requires Electron 30 or later.* > [!NOTE] > This package is native ESM and no longer provides a CommonJS export. If your project uses CommonJS, you will have to convert to ESM. More info about Electron and ESM. Please don't open issues for questions regarding CommonJS and ESM. Usage API Changes are written to disk atomically, so if the process crashes during a write, it will not corrupt the existing config. Store(options?) Returns a new instance. options Type: defaults Type: Default values for the store items. **Note:** The values in will overwrite the key in the option. schema type: JSON Schema to validate your config data. Under the hood, the JSON Schema validator ajv is used to validate your config. We use JSON Schema draft-2020-12 and support all validation keywords and formats. You 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. See more here. Example: **Note:** The value will be overwritten by the option if set. migrations Type: **Important: I cannot provide support for this feature. It has some known bugs. I have no plans to work on it, but pull requests are welcome.** You can use migrations to perform operations to the store whenever a version is upgraded. The object should consist of a key-value pair of . The can also be a semver range. Example: beforeEachMigration Type: \ Default: The given callback function will be called before each migration step. The function receives the store as the first argument and a context object as the second argument with the following properties: • - The version the migration step is being migrated from. • - The version the migration step is being migrated to. • - The final version after all the migrations are applied. • - All the versions with a migration step. This can be useful for logging purposes, preparing migration data, etc. Example: name Type: \ Default: Name of the storage file (without extension). This is useful if you want multiple storage files for your app. Or if you're making a reusable Electron module that persists some data, in which case you should **not** use the name . cwd Type: \ Default: Storage file location. *Don't specify this unless absolutely necessary! By default, it will pick the optimal location by adhering to system conventions. You are very likely to get this wrong and annoy users.* If a relative path, it's relative to the default cwd. For example, would result in a storage file in . encryptionKey Type: \ Default: Note that this is **not intended for security purposes**, since the encryption key would be easily found inside a plain-text Node.js app. Its main use is for obscurity. If a user looks through the config directory and finds the config file, since it's just a JSON file, they may be tempted to modify it. By providing an encryption key, the file will be obfuscated, which should hopefully deter any users from doing so. When using , the config file is authenticated. If the file is changed in any way, the decryption will fail. With and , tampering can go undetected. When specified, the store will be encrypted using the option (defaults to ). encryptionAlgorithm Type: \ Default: Encryption algorithm to use when is set. Use if you want authentication, otherwise use or . Changing will make existing encrypted data unreadable. When using or , existing plaintext config files are not supported. Delete the config file or migrate it before enabling encryption. With , existing plaintext config files are still readable for backward compatibility. fileExtension Type: \ Default: Extension of the config file. You would usually not need this, but could be useful if you want to interact with a file with a custom file extension that can be associated with your app. These might be simple save/export/preference files that are intended to be shareable or saved outside of the app. clearInvalidConfig Type: \ Default: The config is cleared if reading the config file causes a . This is a good behavior for unimportant data, as the config file is not intended to be hand-edited, so it usually means the config is corrupt and there's nothing the user can do about it anyway. However, if you let the user edit the config file directly, mistakes might happen and it could be more useful to throw an error when the config is invalid instead of clearing. serialize Type: \ Default: Function to serialize the config object to a UTF-8 string when writing the config file. You would usually not need this, but it could be useful if you want to use a format other than JSON. deserialize Type: \ Default: Function to deserialize the config object from a UTF-8 string when reading the config file. You would usually not need this, but it could be useful if you want to use a format other than JSON. accessPropertiesByDotNotation Type: \ Default: Accessing nested properties by dot notation. For example: Alternatively, you can set this option to so the whole string would be treated as one key. watch Type: \ Default: Watch for any changes in the config file and call the callback for or if set. This is useful if there are multiple processes changing the same config f…