Module Import Strategies

There are several ways of consuming modules in JavaScript, and we try to support the most common practices.

The EcmaScript import-syntax is the default way of loading the jabra-js library. This syntax has become universal due to recent support in both Node and Chromium browsers. The native syntax has changed slightly compared to the way most bundlers have implemented it previously, so we have seen the need for different import options as well.

The jabra-js codebase is more or less identical for Node and the browser, and unless stated otherwise, APIs are available in both contexts. Nevertheless, we provide different bundles for Node and the browser, mainly to avoid importing unnecessary code.

Module formats#

What module format should you use? It depends on your build setup and platform target. In this section, we will go through our recommendations.

EcmaScript module (browser without a bundler)#

Chromium-based browsers recently started to support the EcmaScript import syntax natively. It has a few caveats compared to what you may be used to if transpiling code via a bundler. First of all, the script tag needs to have the type="module" attribute. Secondly, the import path needs to point to the actual JavaScript file (including the file-extension) - this also goes for node_modules, which will not resolve automatically as if the script was bundled.

// index.js

import { init } from './node_modules/@gnaudio/jabra-js/browser-esm/index.js'; // Note the explicit .js file extension

init().then((api) => {
  // Library initialized...
});

<!-- index.html -->

<html>
  <head>
    <script src="index.js" type="module"></script>
  </head>
</html>

EcmaScript module (browser with a bundler)#

Depending on the concrete configuration, most bundlers - like Webpack or Rollup - will resolve module paths automatically. We have set the EcmaScript-module for the browser as the default package-output, so it can be imported using the node_modules identifier.

import { init } from '@gnaudio/jabra-js';

UMD module (browser)#

As an alternative to the EcmaScript-module, we provide a UMD build. This format is useful if you load the library directly on your website through a script tag. The UMD format will furthermore protect the global namespace by collecting all package exports under jabra.

<html>
  <head>
    <script src="./node_modules/@gnaudio/jabra-js/browser-umd/index.js"></script>

    <script>
      // The module will be loaded into global scope as `jabra`
      jabra.init().then((api) => {
        // Library initialized...
      });
    </script>
  </head>
</html>

EcmaScript module (Node)#

Node.js version 13+ supports EcmaScript-syntax natively. It requires that you add "type": "module" to your package.json. We have found this syntax to work really well in our experiments, but, other 3rd party vendors may not support it yet, so check dependency compatibility before choosing this format.

Like in the browser, the module needs to point to the index.js, however, Node can resolve the node_modules path:

import { init } from '@gnaudio/jabra-js/node-esm/index.js'

CommonJS module (Node)#

We also support the CommonJS module format - the require-syntax - which is available in all Node versions. Please note that the path-name is different than the EcmaScript-module. Also, require only needs to point to the folder, not the specific index-file:

const jabra = require('@gnaudio/jabra-js/node-cjs');

Conclusion#

Internally we prefer the EcmaScript-syntax (no bundling) in both Node and the browser as it seems to be the way forward for the JavaScript community. However, it is early days of a universal module format and we have found that most 3rd party tooling - at the time of writing - does not offer full support for the native implementations of the EcmaScript specification. In many cases, you would need a bundler or transpiler, and these tools seem to prefer the "EcmaScript module (browser with a bundler)" and "CommonJS module (Node)" options for the time being.

Namespaces#

The EcmaScript format offers an easy syntax for handling namespaces, so if you find the jabra-js names to clash with the namespace of your app, you can use the import-as syntax:

import { init as jabraInit } from '@gnaudio/jabra-js';

import * as jabra from '@gnaudio/jabra-js';

Be careful about the latter if using a browser bundler that supports tree-shaking. It may cause the algorithm to include more code than necessary.

Iframe#

If you load the library in an iframe from another domain, and you wish to use the WebHID transport mechanism, then hid needs to be added to the allow-property.

<iframe src="https://example.com..." allow="hid"></iframe>