JavaScript is a language that doesn't stop evolving under the influence of web application developers. Moreover, the will to reuse components from one project to another and to ease the creation of web interfaces lead to the emergence of numerous systems of modules, of packaging, and of interface design frameworks. This lead in turn to multiple ways to integrate our library, depending on the framework used. Here is a short summary of the current situation and of the latest news.
We can't publish a distinct library per existing framework or JavaScript packaging system. We would need tens of them and their number would increase all the time. So we selected to create only one library for JavaScript/ECMAScript, but that you can use with all the main frameworks, through standard integration mechanisms.
Selected standards
Two criteria define de facto what can be used in JavaScript. They are:
- Generalized support in web browsers
- Support in Node.js
After painful beginnings in the early 2000's, where each browser editor added extensions without concertation, the JavaScript language was standardized under the leadership of the ECMA organisation, which publishes each year a new ECMAScript version which makes official the new features approved by standardization committees, after a rigorous debate and selection process. These features are usually quickly embedded in the browsers and into Node.js. The ECMAScript standardization is therefore a third criterium defining what we accept to use in our library.
Supported inclusion methods for our library
Here are the different ways in which inclusions are supported, from the oldest to the newest, with a few words on the implications of each method.
HTML traditional method
To load our library in a simple HTML page, you only need to use a <script src="..."> tag:
<script src="yoctolib-es2017/yocto_api.js"></script>
<script src="yoctolib-es2017/yocto_temperature.js"></script>
...
The browser loads all the .js files in a global environment and you can therefore use all the defined classes in all the scripts on the page.
The library automatically detects that it is used in a browser and performs network access through system classes provided by the browser.
For a complete example of a traditional inclusion in HTML, you can read this tutorial.
Node.js traditional method
The traditional method to define and load modules in Node.js is called CommonJS. You can use it with the require() function which loads the selected module. The example above can therefore be rewritten in Node.js as follows:
require('yoctolib-es2017/yocto_temperature.js');
If you'd rather load the whole library without explicitly listing the classes to be included, you can also use:
Note that to allow direct portability of the code from one version to another, our CommonJS inclusion directly exports all the selected classes in the global environment, without you needing to prefix them with the name of a package symbol. This can be avoided if necessary.
The library automatically detects that it is used in a Node.js environment and performs network access with the Node.js libraries.
To make the use in Node.js easier, our library is available in the npm repository and you can therefore add it to a Node.js project with the command:
npm install yoctolib-es2017
You can also use it with other dynamic package managers more evolved than npm, for example those which perform on demand loading of the modules. You must however make sure that our library prerequisites (such as the ws library providing WebSocket access) are available.
For a complete example of traditional inclusion in Node.js, you can read this tutorial.
Hybrid environments (aka Electron)
Some development environments combine Node.js and a browser in the same application to combine portability of a web display with the liberty of a full access to resources provided by Node.js. In this case, the JavaScript node is launched in a Node.js environment, and it's the method for Node.js which applies.
The library automatically detects that it is used in a Node.js environment and performs network access through the Node.js libraries, independently from the fact that there is also a browser in the application. There is one pitfall to avoid if you start using the Yoctopuce library from the UI process rather than from the main process: the library might not be able to locate the expected Node.js librairies (namely the WebSocket library). That problem can be solved by forcing the Yoctopuce library to use the browser classes to networking, by adding just after the library import the following code:
For a complete example of use with Electron, you can read this post.
The new ECMAscript method (EM modules)
ECMAScript introduced in 2016 a new harmonized module system, which looks somewhat like the module systems of other languages such as Python and C#. As it starts now to be widely accepted, incuding in Node.js, we have decided to support it as well.
This module system is declarative and static, which has the advantage of allowing a resolution of dependencies without having to execute the code, on the opposite of traditional Javascript module systems. This also makes it possible to detect the use of undefined symbols.
However, this declarative system does not allow anymore to offer a single version of the library that runs both in a browser and in Node.js, as including Node.js modules that don't exist in a browser triggers an error. We therefore had to extract everything node-specific in a separate file, and to produce two separate version of the library for use as ECMAScript module: one for use in an HTML page in a browser, and the other for use with Node.js.
Here is the syntax for use in an HTML page:
import { YAPI, YErrorMsg, YModule } from './yoctolib_esm_html/yocto_api.mjs';
import { YTemperature } from './yoctolib_esm_html/yocto_temperature.mjs';
...
</script>
The syntax is identical for use in Node.js, with the exception of the reference to the library yoctolib-esm itself. The package must be explicitly listed in the project dependencies of course:
import { YTemperature } from 'yoctolib-esm/yocto_temperature.mjs';
For complete examples showing how to use the library as an ECMAScript module, see the new examples named Prog-ESModule in our library for JavaScript/ECMAScript. There is one in directory example_html, and another one in directory example_nodejs.
At first glance, one could think that this new way of importing modules is just a change in writing. But it is actually more than that. Indeed, ECMAScript modules are loaded in a very different context by the browser and Node.js. The possibility to load our library in this way therefore makes it easier for you to include our library for all environments that use ECMAScript modules as a native method, such as TypeScript. But we will talk about it some more soon...