Balena Settings Client

Common errors

• ERR_REQUIRE_ESM: Must use import to load ES Module

  cause 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

  cause 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

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

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

Warnings

• breaking Version 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.
• breaking The `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;`
• gotcha This 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.
• gotcha This 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.
• breaking Version 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.

Install

• npm install balena-settings-client npm
• yarn add balena-settings-client yarn
• pnpm add balena-settings-client pnpm

Imports

• settings
  wrong:

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

  correct:

  import settings from '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
  wrong:

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

  correct:

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

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

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

  correct:

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

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

Quickstart

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);