Working with the yFiles npm Module

The yFiles for HTML library is composed of several JavaScript module files, allowing for smooth integration into modern JavaScript projects.

The library is provided as an npm module, which can be easily included in your project. We recommend using yFiles for HTML as an npm module for the best development experience.

The yfiles.css file included with the library is optional. If you load it explicitly, no <style> element is added to the DOM when instantiating a GraphComponent.For more information, see also Default Look and Feel.

Unfortunately, simply running npm install @yfiles/yfiles will not work because, as a commercial product, yFiles is not published to the public npm registry.

This section presents several options for installing yFiles as an npm dependency.

Installing from the Local Filesystem

The easiest way to install the yFiles for HTML npm package is by using a local file path. After you have extracted the yFiles package, you will have the following npm packages to choose from:

• lib/yfiles-<version>.tgz
• lib/yfiles-<version>+dev.tgz

See Development Mode for more details on these variants.

To install a package, run npm install with the path to the desired file:

> npm install <yFiles package path>/lib/yfiles-30.0.0+dev.tgz

Alternatively, you can manually add the dependency to your package.json file and then run npm install:

{
  "dependencies": {
    "@yfiles/yfiles": "<yFiles package path>/lib/yfiles-30.0.0+dev.tgz"
  }
}

It is recommended that you always depend on the .tgz file of the library.You could also provide the path to the extracted folder as an npm dependency instead. However, this is not recommended, as recent versions of npm will create a symlink in the node_modules folder. This might confuse some build tools and produce unexpected results.

Installing from a Remote Filesystem

When installing from your local filesystem, the path to the yFiles library must be correct. You can use a relative path if you copy the yFiles package to the correct location, or you can use an absolute path, but then everyone must use the same path. Neither of these options is ideal.

This is where a central location is useful. Copy the .tgz archive of the yFiles library to a location that is accessible by every machine that needs it, such as a NAS:

> cp <yFiles package path>/lib/yfiles-30.0.0+dev.tgz //my-nas/vendors/yfiles/

Then, you can install it from that location and you do not have to worry about the path:

> npm install //my-nas/vendors/yfiles/yfiles-30.0.0+dev.tgz

Installing from a Local or Private npm Registry

Just because yFiles is not available via the public npm registry, does not mean you cannot install it from your own local or private registry. Simply publish it to your registry and install it like your other modules.

Make sure not to publish yFiles to the public npm registry!

Since the yFiles npm package is scoped, you can associate the @yfiles scope with your private registry:

> npm config set @yfiles:registry=https://reg.example.com

See the official npm documentation of scopes for more details.

Installing from a Local git Server

If you have a private or local git server, you can create a new repository there and then push the yFiles npm package to it.

Make sure that you do not publish yFiles to a public Git repository!

Afterward, you can install the yFiles dependency using a git link:

> npm install git+http://your-git-server/path/to/repo.git

Note that you must push the actual npm package to the repository. This means pushing the extracted <yFiles package path>/lib/yfiles-30.0.0+dev.tgz archive, so that the library’s package.json file resides at the top level in the repository.

The Version Number of the yFiles npm Package

yFiles versions have traditionally used a four-part version number, such as 3.0.0.1. The first two digits represent the major version, the third indicates the minor version, and the last signifies the bugfix level.

To comply with Semantic Versioning and provide a three-part npm version number, the first two digits of the yFiles version are combined to form the first digit of the npm package version, while the remaining two digits are retained. For example, release 3.0.0.1 corresponds to the npm module version 30.0.1.

To differentiate an evaluation package from a non-evaluation package of yFiles for HTML, the npm version number of the evaluation package includes the +eval postfix. For example, 30.0.1+eval. Additionally, the "Development Mode" library has the postfix +dev, for example, 30.0.1+dev, or 30.0.1+eval-dev.