Home

Awesome

Balena SDK

The official JavaScript balena SDK.

npm version dependencies Build Status Build status

Role

The intention of this module is to provide developers a nice API to integrate their JavaScript applications with balena.

Installation

Install the balena SDK by running:

$ npm install --save balena-sdk

Platforms

We currently support NodeJS (18+) and the browser.

The following features are node-only:

In Node you can simply require('balena-sdk'), but in the browser things are more complicated. The balena SDK provides a bundled single file for browsers, which allows you to include a single file with all dependencies included, available as balena-browser.min.js. This uses the UMD format, and will register itself as either a CommonJS or AMD module called balena-sdk if possible, or create a balenaSdk global if not. You can also use the es2018 version if desired.

Bundling for browsers

If you're using webpack, browserify, or a similar tool then you probably want to bundle the balena SDK into your application yourself, rather than using the pre-built balena-browser.min.js bundle. If you do that, you should be aware that you may pick up some dependencies that are actually unnecessary in the browser, because they're only used in Node environments. You can safely exclude these dependencies, if you're not using them yourself, and significantly reduce the size of your resulting bundle.

In the browser the balena SDK doesn't use the following dependencies:

For the future we're looking at ways to automatically exclude these in downstream bundles. See #254 for more information.

Bundling with pkg

The balena SDK includes builds for various ECMAScript versions that are dynamically selected at runtime (using @balena/es-version). For this reason, packagers like pkg are not able to automatically detect which assets to include in the output package. The following sample pkg section should be added to your application's package.json file to instruct pkg to bundle the required assets:

  "pkg": {
    "scripts": [
      "node_modules/balena-sdk/**/*.js"
    ],
    "assets": [
      "node_modules/pinejs-client-core/**/*"
    ]
  }

For more information, please refer to the respective documentation from the pkg project.

Documentation

The module exports a single factory function. Use it like this:

var balena = require('balena-sdk')({
	apiUrl: "https://api.balena-cloud.com/",
	dataDirectory: "/opt/local/balena"
})

Where the factory method accepts the following options:

See the JSDoc markdown documentation for the returned balena object in DOCUMENTATION.md.

Support

If you face any issues, please raise an issue on GitHub and the balena team will be happy to help.

Deprecation policy

The balena SDK uses semver versioning, with the concepts of major, minor and patch version releases.

The latest release of the previous major version of the balena SDK will remain compatible with the balenaCloud backend services for one year from the date when the next major version is released. For example, balena SDK v12.33.4, as the latest v12 release, would remain compatible with the balenaCloud backend for one year from the date when v13.0.0 is released.

At the end of this period, the older major version is considered deprecated and some of the functionality that depends on balenaCloud services may stop working at any time. Users are encouraged to regularly update the balena SDK to the latest version.

Tests

In order to run the balena SDK test suite, set the following environment variables from an account that exists and doesn't have a billing account code: WARNING: This will delete all applications and public keys of the test users. As such, all emails are required to contain the string +testsdk to avoid accidental deletion

You also have to provide the following environment variables from an account that doesn't yet exist:

In order to test the billing methods for a paid account, you also have to configure the following environment variables:

Note: The paid user's account billing code should be set to testdev so that it's tested against the test plan.

You can also, optionally, set the TEST_API_URL environment variable in order to run the tests using a different API backend (eg: https://api.balena-staging.com).

You can persist these settings by putting them all into a .env file in the root of this repo, in dotenv format (KEY=VALUE\n). This will be automatically detected and used in the tests. Make sure you don't accidentally commit this file (.env by default is gitignored, so hopefully this should be difficult).

Run the test suite by doing:

$ npm test

In order to make the develop & test cycle faster:

Contribute

Before submitting a PR, please make sure that you

$ npm run lint-fix
$ npm test

License

The project is licensed under the Apache 2.0 license.