ES5 Compatibility

If your yFiles for HTML application needs to support older browsers, such as Internet Explorer 11, that do not implement the ECMAScript 2015/ES6 standard, you will typically need some sort of build toolchain that compiles the application sources and libraries to ES5. This chapter discusses how to achieve ES5 compatibility for various scenarios.

Since the yFiles for HTML library itself does not use ES2015 features other than those few shimmed in the ECMAScript 2015 Shim (e.g. Promises), an application written in plain ES5 that uses the UMD variant of the library will not need any transpilation whatsoever to work in ES5-only browsers. However, since only very few applications and libraries are still written/provided in plain ES5 nowadays, most JavaScript projects will use some kind of build toolchain that creates the artifacts for production deployment.

ECMAScript 2015 Shim

The yFiles for HTML library uses ECMAScript 2015 features that are not present in some of the supported browsers (e.g. Promises). Therefore, if your yFiles for HTML application should be compatible with older browsers that do not fully support ECMAScript 2015, you will have to include a shim/polyfill JavaScript file that provides implementations for these features.

The yFiles for HTML package comes with a minimal shim file that provides just those features that are used by the yFiles for HTML library. After unpacking the library this basic shim can be found next to the extracted library modules at lib/umd/es2015-shim.js. To use the shim in your application, just reference it with a regular <script> tag:

<script src='lib/umd/es2015-shim.js'></script>'

Note that this shim does not provide a full ES2015 environment by any means. For full ES2015 support, we recommend to use one of the more exhaustive ES2015 shims that are available instead, e.g. core-js with regenerator-runtime.

ES5 Compatibility in a Toolkit Project

When integrating yFiles into a project that uses one of the popular JavaScript frameworks like e.g. React, Angular, or Vue.js, the project should already be set up to produce ES5-compatible production output. Most of these toolkits come with a CLI that will scaffold a setup which includes Babel for enabling backwards compatibility with older browsers. In that case, yFiles can simply be added to these kinds of projects as an additional NPM dependency. Please have a look at the section about toolkit specific advice to find tips and samples for the individual toolkits.

ES5 Compatibility in General

As explained in Working with yFiles and as shown in almost all sample applications, the most convenient way to work with yFiles is to use the ES Modules variant of the library. However, static imports are not supported by older browsers, and when using symbolic names, a build step is required even for modern browsers.

Also, since it is much more convenient and effective to write a JavaScript application when modern language features can be used, a transpilation step will be necessary as well.

Webpack + Babel

A common approach to satisfy the requirements for a bundling step (to account for the symbolic imports) and a transpilation step is to use webpack with the babel-loader.

Rollup + Babel

Rollup can be used as an alternative to webpack for resolving ES module imports and bundling the application. In combination with the @rollup/plugin-babel, an ES5 compatible bundle can be created.