yFiles Library Formats

The yFiles for HTML API is divided into a number of ES modules for seamless integration into modern JavaScript projects. We recommend using this variant for almost all yFiles for HTML projects.

For those few use cases where using ES modules is not an option, the package also contains a UMD version of the library. This variant is only recommended for Node.js applications and for projects where yFiles for HTML will be loaded using an AMD loader or browser globals.

Both library variants come as npm modules that can be easily included in your project. We recommend using yFiles for HTML as a npm module for an optimal development experience.

The yfiles.css file, which is provided with the library, is optional. If it is loaded explicitly, no <style> element is added to the DOM during instantiation of a GraphComponent.For more information see also Default Look and Feel.

ES Modules

The ES module library is suitable for most new yFiles for HTML projects, as it integrates seamlessly with modern JavaScript build tools and IDEs. These modules can be loaded in browsers that support the import statement and used with tools that expect JS Modules as input.

ES Module dependencies gives an overview of the dependencies between these modules. Note that the yfiles/lang and yfiles/core modules are omitted from the diagram since all modules depend on these modules. For brevity and clarity, the diagram also does not show transitive dependencies and omits the 'yfiles/' prefix in modules names.

Here is a brief overview of the various JS Modules and their contents:

Importing the ES Modules of yFiles for HTML

You can load yFiles for HTML by using the JS Module variant of the library and import statements:

import { GraphComponent } from '../../node_modules/yfiles/yfiles.js'
const graphComponent = new GraphComponent()

This syntax is supported natively by most modern browsers.

For the best developer experience, you can use symbolic names for the imports instead of the full path:

import { GraphComponent } from 'yfiles'
const graphComponent = new GraphComponent()

For this to work, some tool has to resolve these symbolic names to real paths. One such tool is webpack. Additionally, the web server that is included in the yFiles for HTML package is able to resolve references to the yFiles library, which is why most of the demos use the symbolic names in their imports.

Using the symbolic name also provides the advantage that most IDEs offer superior code completion and documentation lookup for this kind of imports.

InvalidOperationError: Missing module

During development, you might encounter an error message like this:

Missing module: This feature requires the 'view-layout-bridge' module of yfiles. To make sure it’s loaded, add the line 'Class.ensure(LayoutExecutor)'.

The solution is to follow the instructions in the message and add the suggested line to your application. In the above example, this would be

Class.ensure(LayoutExecutor)

The cause is that, internally, the yFiles modules don’t use strict imports to get types from the modules they depend on. Instead, they are only loosely coupled. This makes it possible for build tools to remove unused modules with optimizations like tree shaking.

However, it can happen that a build optimization removes a module that is actually needed. In this case, the missing module error is thrown.

The solution recommended in the error message makes sure that an explicit import of a type of the missing module is added to your project, thus requiring the optimization to include that module. In the above example, this would be the LayoutExecutor class from the view-layout-bridge module:

Alternatively, make sure that the named module is included in your build tool’s configuration.

UMD Modules

The yFiles for HTML package contains a version of the library in UMD format. It provides the same "flat" API as the ES module variant. Additionally, the legacy namespaced API is also still available for backwards compatibility:

// new "flat" API
const { GraphComponent } = yfiles
const graphComponent = new GraphComponent()

// legacy namespaced API
const graphComponent = new yfiles.view.GraphComponent()

Modules that make use of the UMD API can be loaded in various environments:

• Asynchronous Module Definition (AMD) - Modules are loaded lazily using an AMD loader like RequireJS.
• CommonJS — Used in Node.js applications.
• Browser Globals — Simply access the yFiles functionality through the global yfiles root object.

Module dependencies gives an overview of the dependencies between these modules. Note that module yfiles/lang is omitted from the diagram since all modules depend on that module. For brevity and clarity, the diagram also does not show transitive dependencies.

Here is a brief overview of the various UMD modules and their contents:

Loading the UMD Modules Using an AMD Loader

AMD loading enables asynchronous module loading, and automatic module resolution.

Once your AMD loader is available, you can call the require function which loads the desired yFiles for HTML modules and their dependencies and then executes a provided callback function.

require.config({
  paths: {
    yfiles: './node_modules/yfiles-umd'
  }
})
require(['yfiles/complete'], ({ GraphComponent, License }) => {
  License.value = {
    /* <add your license information here> */
  }

  // this is where the application code can be placed in
  const graphComponent = new GraphComponent()
})

AMD loading enables asynchronous module loading, and automatic module resolution. For example, load RequireJS from a CDN and include it in your document.

Loading the UMD Modules Using CommonJS

CommonJS is the module loading mechanism of Node.js. As yFiles for HTML comes as a npm module, it can be required like any other node module.

const { GraphComponent } = require('yfiles')

const graphComponent = new GraphComponent()

See the Node.js demo for an example.

Loading the UMD Modules Using Browser Globals

In some environments, the only option to use third-party libraries is to load them as a global variable.

<body>
  <script src="./node_modules/yfiles-umd/impl/lang.js"></script>
  <script src="./node_modules/yfiles-umd/impl/core-lib.js"></script>
  <script src="./node_modules/yfiles-umd/impl/graph-core.js"></script>
  <script src="app.js"></script>
</body>

const { GraphComponent } = yfiles

const graphComponent = new GraphComponent()