Registry / storage / balena-settings-storage

balena-settings-storage

library8.2.0jsnpmunverified

Low-level module for persisting Balena settings in Node.js (filesystem) and browser environments. Version 8.2.0 is current, with a stable API surface focused on simple key-value storage through getStorage(), returning an object with set/get/has/remove/clear methods. Ships TypeScript types, supports ESM and CJS, requires Node >=14. Replaces the deprecated 'balena-settings-client'. Not intended for end users; use the high-level Balena SDK instead.

storage

npm install balena-settings-storage

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BALENA-SETTINGS-ST

balena-settings-storage

storagejavascriptv8.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

getStorage

✓ import { getStorage } from 'balena-settings-storage'

✗ const getStorage = require('balena-settings-storage').getStorage

Named import only; no default export.

storage instance

✓ const storage = getStorage({ dataDirectory: '/tmp' })

✗ const storage = getStorage()

Pass options object; missing dataDirectory defaults to platform-specific or in-memory.

set/get

✓ storage.set('key', 'value'); storage.get('key')

✗ storage.set({key: 'value'})

Method signatures require separate name and value arguments, not an object.

Demonstrates basic CRUD operations: set, get, has, remove using the storage instance obtained via getStorage.

import { getStorage } from 'balena-settings-storage'; const storage = getStorage({ dataDirectory: '/opt/balena/cache' }); async function main() { await storage.set('token', 'abc123'); const token = await storage.get('token'); console.log(token); // 'abc123' const exists = await storage.has('token'); console.log(exists); // true await storage.remove('token'); console.log(await storage.has('token')); // false } main().catch(console.error);

Debug

Known issues

breakingIn version 8.0.0, the module was converted to ESM-only. CommonJS require() will not work.

fix

Use import syntax or if on Node, use dynamic import().

affects: >=8.0.0

deprecatedThe balena-settings-client package is deprecated in favor of balena-settings-storage.

fix

Switch to balena-settings-storage with updated API (getStorage pattern).

affects: >=6.0.0

gotchadataDirectory option is ignored in browser environments; settings are stored in localStorage.

fix

Do not rely on dataDirectory behavior in browser; use false to force in-memory storage in Node.

affects: >=1.0.0

gotchaget() returns undefined for missing keys, not null. Doing loose comparison may cause bugs.

fix

Use storage.has() to check existence before get().

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: balena_settings_storage_1.getStorage is not a function

Default import used instead of named import

fix

Change import balenaSettingsStorage from 'balena-settings-storage' to import { getStorage } from 'balena-settings-storage'

Error: Cannot find module 'balena-settings-storage'

Package not installed or wrong import path

fix

Run npm install balena-settings-storage and ensure import path is correct

TypeError: storage.set is not a function

getStorage() was called without the required options object, returning undefined

fix

Call getStorage({ dataDirectory: 'path' }) instead of getStorage()

Upgrade

Version history

8.2.0latest on npm

Audit

Dependencies

lodashrequiredUtility functions for internal operations

Agent activity

47 hits · last 30 days

node

Resources

githubgit://github.com/balena-io-modules/balena-settings-storage ↗

packagebalena-settings-storage ↗

homepagehttps://github.com/balena-io-modules/balena-settings-storage ↗