Migrating to ESM

What’s new in HOOPS Communicator

This document is intended to describe the differences between HC version 24.2.0 and previous versions, especially related to ESM. For an overview of ESM, see our page on ESM.

What is in the box?

Everything ESM related is located in the web_viewer/esm directory of the package. In this directory you will find the following content:

The engine

  • engine.esm.js

  • engine.esm.wasm

The Web Viewer

  • hoops-web-viewer.mjs - This file contains the Web Viewer’s code as an ES Module

  • hoops-web-viewer.iife.mjs - This file is equivalent to hoops_web_viewer.js file in versions prior to 24.2.0

  • hoops-web-viewer.umd.js - This file contains the Web Viewer’s code as an UMD, it can be loaded through RequireJS.

Note

As you can see, the naming convention has slightly changed to follow Node.js recommendations.

The Monolithic Web Viewer

  • hoops-web-viewer-monolith.mjs

  • hoops-web-viewer-monolith.iife.mjs

  • hoops-web-viewer-monolith.umd.js

Another advantage of moving to ESM is that the monolithic version of the code is also available in three versions.

> A types directory containing the type declarations

> An examples directory which contains the developer samples, it is equivalent to web_viewer/examples but using ES Modules.

> A demo-app directory which contains the code of our demo application, it is equivalent to web_viewer/src but slightly different.

You will also notice that applications directory names has also changed in order to follow MDN recommendations.

The js directories are now named scripts.

Aside from the new file and directory names you will notice that the demo app code is not bundled into js/web_viewer_ui.js. The entire code is now written in humanly readable Javascript (it is transpiled from Typescript unminified and unbundled) in web_viewer/esm/demo-app/web-viewer-demo/src so you can navigate the code. This is equivalent to web_viewer/typescript/ui, but implemented using ES Modules

General API changes for 24.2.0

  • Every Web Viewer API deprecated prior to HC 24.2.0 has been removed.

  • The path to the engine’s directory is now necessary to load your engine.esm.js and engine.esm.wasm.

  • Due to the different way to integrate the Web Viewer library into your application there is no solution that would satisfy everyone. In many cases, document.currentScript would be null, import.meta.url would not be supported or it may not point to the appropriate location, etc. Therefore, it is now required for the user to set the enginePath when creating a WebViewer object.

    However, it can be handy not to have to set the enginePath on construction. In this case, you can set the defaultEnginePath on the WebViewer class then whenever you instantiate a WebViewer without specifying the enginePath, it will use the defaultEnginePath to locate the engine’s files.

ESM-specific API changes

If you are using ESM there is no need for you to prefix the components you need with Communicator. For example:

import { WebViewer } from 'hoops-web-viewer.mjs';

const hwv = new WebViewer({
  // ...
});

However, you can still use the Communicator prefix using aliased import:

import * as Communicator from 'hoops-web-viewer.mjs';

const hwv = new Communicator.WebViewer({
  // ...
});

Communicator.Operator is now Operators.

import { Operators } from 'hoops-web-viewer.mjs';

// ...

const op = new Operators.AxisTriadOperator(/* ... */);

BCF-related objects are now under Bcf namespace.

import { Bcf } from 'hoops-web-viewer.mjs';

// ...

const markup = new Bcf.BCFMarkup(/* ... */);

Floorplan-related objects are now under Floorplan namespace.

import { Floorplan } from 'hoops-web-viewer.mjs';

// ...

const fp = new Floorplan.FloorplanConfig(/* ... */);