Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

balena-settings-client

balena-io-modules46.4kApache-2.05.0.3TypeScript support: included

Balena client application shared settings

balena, settings, client

readme

balena-settings-client

npm version dependencies Build Status Build status

Join our online chat at Gitter chat

Balena client application shared settings.

Role

The intention of this module is to provice low level access to user configurable balena simple settings.

THIS MODULE IS LOW LEVEL AND IS NOT MEANT TO BE USED BY END USERS DIRECTLY.

Unless you know what you're doing, use the balena SDK instead.

Installation

Install balena-settings-client by running:

$ npm install --save balena-settings-client

Documentation

This module attempts to retrieve configuration from the following places:

UNIX:

  • Default settings.
  • $HOME/.balenarc.yml.
  • $PWD/balenarc.yml.
  • Environment variables matching BALENARC_<SETTING_NAME>.

Windows:

  • Default settings.
  • %UserProfile%\_balenarc.yml.
  • %cd%\balenarc.yml.
  • Environment variables matching BALENARC_<SETTING_NAME>.

The values from all locations are merged together, with sources listed below taking precedence.

For example:

    $ cat $HOME/.balenarc.yml
    balenaUrl: 'balena-staging.com'
    projectsDirectory: '/opt/balena'

    $ cat $PWD/.balenarc.yml
    projectsDirectory: '/Users/balena/Projects'
    dataDirectory: '/opt/balena-data'

    $ echo $BALENARC_DATA_DIRECTORY
    /opt/cache/balena

That specific environment will have the following configuration:

    balenaUrl: 'balena-staging.com'
    projectsDirectory: '/Users/balena/Projects'
    dataDirectory: '/opt/cache/balena'

settings~get(name) ⇒ *

Kind: inner method of settings
Summary: Get a setting
Returns: * - setting value
Access: public

Param Type Description
name String setting name

Example

settings.get('dataDirectory')

settings~getAll() ⇒ Object

Kind: inner method of settings
Summary: Get all settings
Returns: Object - all settings
Access: public
Example

settings.getAll()

Modifying settings

This module is intended to only provide read only access to the settings. Balena settings client reads settings from various locations, like a local balenarc file and a per user config file, therefore the module doesn't know where to write changes back.

If you want to persist data related to balena, consider using balena settings storage instead.

Support

If you're having any problem, please raise an issue on GitHub and the balena team will be happy to help.

Tests

Run the test suite by doing:

$ npm test

Contribute

Before submitting a PR, please make sure that you include tests, and that coffeelint runs without any warning:

$ npm run lint

License

The project is licensed under the Apache 2.0 license.

changelog

Change Log

All notable changes to this project will be documented in this file automatically by Versionist. DO NOT EDIT THIS FILE MANUALLY! This project adheres to Semantic Versioning.

v5.0.3

(2023-06-02)

  • Update TypeScript to 5.1.3 [Thodoris Greasidis]

v5.0.2

(2023-04-21)

  • Update Typescript to v5.0.2 to fix master [Thodoris Greasidis]
  • Disable package-lock.json generation [Thodoris Greasidis]
  • Replace balenaCI with flowzone [Thodoris Greasidis]

v5.0.1

(2022-05-03)

  • Stop running tests on appveyor [Thodoris Greasidis]

v5.0.0

(2022-05-03)

  • Drop the imageMakerUrl default setting [Thodoris Greasidis]

v4.0.7

(2021-06-30)

  • Delete CODEOWNERS [Thodoris Greasidis]

v4.0.6

(2021-01-20)

  • defaults: Add tunnelUrl to return a computed value [Rich Bayliss]

v4.0.5

(2020-04-21)

  • Update dev dependencies [Pagan Gazzard]

4.0.4 - 2020-03-02

  • Lazy-load js-yaml [Pagan Gazzard]

4.0.3 - 2020-02-28

  • Use declaration files for the types [Pagan Gazzard]
  • Do not include build output in the repo [Pagan Gazzard]

4.0.2 - 2019-09-11

  • Dependencies: Update dependencies and build rules [Heds Simons]

v4.0.1 - 2018-10-24

  • Continue to support resinrc.yml config files [Tim Perry]
  • Continue to support RESINRC_ environment variables [Tim Perry]

v4.0.0 - 2018-10-15

  • Rename everything 'resin' to 'balena' [Tim Perry]

v3.8.8 - 2018-07-20

  • Re-enable testing in Node 10 #53 [Tim Perry]

v3.8.7 - 2018-05-02

  • Fix deploy attach_workspace configuration #52 [Tim Perry]

v3.8.6 - 2018-05-02

  • Deploy using node 8 + npm 4 #51 [Tim Perry]

v3.8.5 - 2018-04-25

  • Pin all type packages #50 [Tim Perry]
  • Stick with home-or-tmp version 2, for max engine compatibility #50 [Tim Perry]

v3.8.4 - 2017-12-13

  • Fix bug in e2e tests that breaks deployment #49 [Tim Perry]

v3.8.3 - 2017-12-13

  • Make sure we have the correct version of npm in circle to publish #48 [Tim Perry]

v3.8.2 - 2017-12-12

  • Set up circleci npm autopublishing #47 [Tim Perry]

v3.8.1 - 2017-11-01

  • Fix typings broken (correctly) by lodash type updates #46 [Tim Perry]
  • Reformat changelog to add versionbot #46 [Tim Perry]

v3.8.0 - 2017-09-25

  • Add registry2Url setting.

v3.7.0 - 2017-08-31

  • Converted sources to TypeScript.

v3.6.1 - 2017-04-22

  • Better error message for malformed YAML

v3.6.0 - 2017-04-19

  • Add bin directory to settings

v3.5.2 - 2016-10-04

  • Update to lodash v4

v3.5.1 - 2016-09-08

  • Make the settings lazy-loaded when they are actually required.

v3.5.0 - 2016-04-22

  • Add proxyUrl setting.

v3.4.2 - 2016-02-03

  • Add deltaUrl setting.

v3.4.1 - 2015-12-04

  • Omit tests from NPM package.

v3.4.0 - 2015-11-16

  • Add imageMakerUrl setting.

v3.3.1 - 2015-11-15

  • Fix getAll() not interpreting dynamic settings.

v3.3.0 - 2015-11-15

  • Implement getAll() function.

v3.2.2 - 2015-11-12

  • Default user home directory to the operating system temporary directory in all instances.

v3.2.1 - 2015-11-09

  • Default user home directory to __dirname.

v3.2.0 - 2015-09-23

Added

  • Add apiKeyVariable setting.

v3.1.0 - 2015-09-07

Added

  • Add vpnUrl setting.
  • Add registryUrl setting.

v3.0.0 - 2015-09-07

Added

  • Implement dynamic default settings.
  • Implement environment variables support.
  • Add new resinUrl setting.
  • Implement e2e test suite.

Changed

  • Improve documentation.
  • Switch to YAML for configuration files.
  • Use $HOME/[._]resinrc.yml for user configuration file.
  • Use resinrc.yml for per project configuration file.

v2.1.0 - 2015-08-12

Added

  • Add projectsDirectory setting.

v2.0.0 - 2015-07-17

Changed

  • Rename tokenValidityTime setting to tokenRefreshInterval.

v1.5.0 - 2015-07-16

Added

  • Added tokenValidityTime setting.

v1.4.0 - 2015-07-01

Added

  • Added cacheDirectory setting.
  • Added imageCacheTime setting.

v1.3.0 - 2015-06-18

Added

  • JSDoc documentation.
  • License to every source files.

Changed

  • Improved README documentation.

v1.2.0 - 2015-06-10

Changed

v1.1.0 - 2015-06-02

Added

  • Add dashboardUrl setting property.

v1.0.1 - 2015-05-18

Added

  • Add .hound.yml configuration file.

Changed

  • Default remoteUrl to api.resin.io.