Registry / devops / balena-settings-client

balena-settings-client

library6.0.3jsnpmunverified

balena-settings-client is a low-level utility module designed to provide read-only access to user-configurable balena application settings. It consolidates configuration from various sources, including default settings, user-specific `.balenarc.yml` files (e.g., `$HOME/.balenarc.yml` on Unix), project-specific `.balenarc.yml` files (`$PWD/balenarc.yml`), and environment variables prefixed with `BALENARC_`. Values are merged with a clear precedence hierarchy, allowing for flexible overrides. The current stable version is 6.0.3, with recent releases indicating active maintenance and development. Key differentiators include its role in the balena ecosystem for managing client-side settings, its ability to merge configurations from multiple sources, and its explicit read-only nature. This module is not intended for direct end-user consumption; instead, users are typically directed to the higher-level `balena-sdk` for interacting with balena services.

devops aws

npm install balena-settings-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BALENA-SETTINGS-CL

balena-settings-client

devopsjavascriptv6.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

settings

✓ import settings from 'balena-settings-client';

✗ const settings = require('balena-settings-client');

Since v6.0.0, the module is primarily ESM-first, requiring Node.js >=20.12.0. Direct `require()` statements might lead to errors in pure ESM projects.

get

✓ import settings from 'balena-settings-client'; settings.get('balenaUrl');

✗ import { get } from 'balena-settings-client'; get('balenaUrl');

The `get` method is typically accessed as a method of the default exported `settings` object, not as a direct named export.

getAll

✓ import settings from 'balena-settings-client'; settings.getAll();

✗ import { getAll } from 'balena-settings-client'; getAll();

The `getAll` method is typically accessed as a method of the default exported `settings` object, not as a direct named export.

This quickstart demonstrates how to initialize the balena-settings-client, read individual settings using `settings.get()`, and retrieve all loaded settings with `settings.getAll()`. It shows how settings from a local `balenarc.yml` file and environment variables are automatically merged and accessed.

import settings from 'balena-settings-client'; import * as fs from 'fs'; import * as path from 'path'; // Create a dummy .balenarc.yml in the current working directory for demonstration const cwdBalenarcPath = path.join(process.cwd(), 'balenarc.yml'); fs.writeFileSync(cwdBalenarcPath, 'projectsDirectory: "/tmp/my-projects-dir"\n'); // Simulate an environment variable process.env.BALENARC_CUSTOM_SETTING = 'some-custom-value'; async function demonstrateSettings() { console.log('--- Reading individual settings ---'); const balenaUrl = settings.get('balenaUrl'); console.log(`balenaUrl: ${balenaUrl || 'Not set (default)'}`); const projectsDirectory = settings.get('projectsDirectory'); console.log(`projectsDirectory (from CWD config): ${projectsDirectory}`); const customSetting = settings.get('customSetting'); console.log(`customSetting (from ENV): ${customSetting}`); console.log('\n--- Reading all settings ---'); const allSettings = settings.getAll(); console.log(JSON.stringify(allSettings, null, 2)); // Clean up the dummy file fs.unlinkSync(cwdBalenarcPath); } demonstrateSettings().catch(console.error);

Debug

Known issues

breakingVersion 6.0.0 dropped support for Node.js versions older than 20.12.0 and requires ES2019 features. Ensure your Node.js environment meets these requirements to avoid runtime errors.

fix

Upgrade your Node.js environment to version 20.12.0 or newer. Consider using a Node.js version manager like `nvm` to manage multiple Node.js installations.

affects: >=6.0.0

breakingThe `get` method no longer supports property paths (e.g., `settings.get('a.b.c')`). Attempting to use property paths will result in the method trying to retrieve a top-level setting with that literal name, likely returning `undefined` or incorrect values.

fix

Refactor code to retrieve the top-level object and then access nested properties manually. For example, instead of `settings.get('api.url')`, use `const apiSettings = settings.get('api'); const url = apiSettings?.url;`

affects: >=6.0.0

gotchaThis module is explicitly designed for low-level, read-only access to settings. It does not provide any API to modify or persist settings because it merges from multiple sources and cannot determine where to write changes back. For persisting data, consider `balena-settings-storage`.

fix

Do not attempt to modify settings through this client. If you need to write configuration, use a dedicated storage mechanism or a higher-level SDK like `balena-sdk` if appropriate for your use case.

affects: >=1.0.0

gotchaThis module is considered low-level and is not meant for direct use by end-user applications. Balena recommends using the `balena-sdk` which provides a more abstract and user-friendly interface for interacting with balena services, including settings.

fix

Evaluate if your use case truly requires direct access to `balena-settings-client`. For most applications, integrating with `balena-sdk` is the recommended approach for managing balena-related configurations.

affects: >=1.0.0

breakingVersion 6.0.0 replaced `lodash` with `es-toolkit` and dropped `Bluebird`. While these are internal dependency changes, if you were relying on implicit `lodash` or `Bluebird` functionality exposed through `balena-settings-client`'s internals, your code might break.

fix

Review your codebase for any indirect dependencies on `lodash` or `Bluebird` through `balena-settings-client`. If found, refactor to use `es-toolkit` or native JavaScript alternatives, or explicitly import `lodash`/`Bluebird` if they are direct dependencies of your project.

affects: >=6.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: Must use import to load ES Module

Attempting to use `require()` to import `balena-settings-client` in a project configured as an ES Module, or when the package itself is treated as ESM.

fix

Change your import statement from `const settings = require('balena-settings-client');` to `import settings from 'balena-settings-client';`. Ensure your project's `package.json` has `"type": "module"` or uses `.mjs` file extensions for ESM.

TypeError: settings.get is not a function

This error typically occurs if `settings` was not correctly imported or if a named import was attempted instead of the default export pattern.

fix

Verify that `balena-settings-client` is imported as `import settings from 'balena-settings-client';` and that `settings.get()` is called on the default exported object.

TypeError: settings.get('nested.path') - Property path access no longer supported

In v6.0.0 and later, the `get` method removed support for retrieving values using dot-notation property paths.

fix

Instead of `settings.get('parent.child')`, first get the parent object: `const parent = settings.get('parent');` then access the child property: `const child = parent?.child;`.

Unsupported Node.js version. balena-settings-client requires Node.js >=20.12.0.

Running the application with a Node.js version older than 20.12.0, which is no longer supported by v6.0.0+.

fix

Update your Node.js environment to version 20.12.0 or newer. Use a tool like `nvm` (Node Version Manager) to easily switch Node.js versions.

Upgrade

Version history

6.0.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/balena-io-modules/balena-settings-client ↗

packagehttps://www.npmjs.com/package/balena-settings-client ↗

homepagehttps://balena.io ↗