# Prerequisites

# Node.js

Our recommended setup is a build pipeline which uses the Node.js ecosystem. Therefore it also makes sense to use some package manager like npm (opens new window) or yarn (opens new window). To keep it "simple" we focus on npm in this tutorial. To install our Web SDK you need to run

npm i @roomle/web-sdk --save

This should add the following line to your package.json

"@roomle/web-sdk": "x.y.z",

Without any version specified this will always lead to the most recent version of the SDK.

To install for example version 2.1.1 just change the entry in your package.json to the following:

"@roomle/web-sdk": "^2.1.1",

When you want to upgrade the version you just need to change the version number. For more details you can see the official npm docs (opens new window).

We follow semantic versioning (opens new window) therefore the versions have the following semantics:

When we have a look on the following version number: X.Y.Z, a change in Z means a bug fix, in Y a new feature and in X a new major version which could be a breaking release. To find out what we changed we recommend reading through our changelog (opens new window) before upgrading.

# Assets

Since our applications are quite complex we do not only have JavaScript files. Therefore a simple packaging is not possible. Roomle uses Three.js (opens new window) to display the 3D content and a WASM (opens new window) module for our logic. Also we provide some standard backgrounds as glb (opens new window) files for our 3D scenes. This requiers you to copy all our static assets to some path which is available via https. These files are all located in node_modules/roomle-web-sdk/lib/static. We recommend doing this automated (and not by hand) with your build tools (esbuild (opens new window), webpack (opens new window), rollup (opens new window) etc).

To tell Roomle where to look for this assets you need to specify a global variable before you load the Roomle source code. We need to use a global variable because we try to load all the stuff as fast and parallel as possible.

# Asset path

<script>
  window.__RML__ENV__ = {
    assetPath: '__REPLACE__WITH__YOUR__PATH__SPECIFIED__IN__PACKAGE__JSON__',
  };
</script>

Typically the assets should be in some folder like public or dist and from there they are available via https. Let's assume your project setup serves from a dist folder at localhost:4242 and you place the Roomle assets into dist/roomle. You have dist/index.html which starts your app and loads Roomle. Then you have to set the assetPath to roomle/. You must not forget the trailing /, because otherwise the sub paths are not constructed correctly.

# TypeScript / ES6 Modules

All the Roomle Packages are authored in TypeScript (opens new window) therefore we provide declaration files for a better developer experience. We recommend to use TypeScript but the SDK should also be useable as a plain ES6 module. Since we develop in TypeScript and do not do any special testing for plain ES6 we consider the usage of the SDK as plain ES6 as experimental. Because Roomle has very hard performance constraints (especially for webshop integrations) we use dynamic imports (opens new window). Since dynamic imports are not supported by every browser it's important to transpile the code to something like SystemJs (opens new window). Keep in mind to provide two different bundles, one for legacy browsers and one for modern browsers. A very interesting article about this topic can be found here: Smart Bundling: How To Serve Legacy Code Only To Legacy Browsers (opens new window)

# Browser compatibility

Since our SDK is focused on high performance and high quality 3D visualization we recommend modern browsers. We suggest to target browser which support ES6 modules, for details see: https://caniuse.com/#feat=es6-module (opens new window). Of course it is possible to do transpile magic and convert the code to some JavaScript version which supports more browsers but this is totally experimental and not supported by this SDK. If you do apply transpile magic, make sure to send the correct bundle to every browser and not a legacy version to everybody. Also keep in mind that browser compatibility is restricted to the constraints of Three.js (opens new window) and WebAssembly (opens new window).

# About the tutorials

We provide a Code Sandbox (opens new window) for all our examples so you can have a look on the entire project setup. Furthermore we use Vue (opens new window) to develop the UI. We really think that it makes sense to use a client-side framework to develop the UI. If you are unsure what a client-side framework is or what benefits it brings we highly recommend reading through the article Introduction to client-side frameworks (opens new window)