documentationfor yFiles for HTML 2.6

Working with the yFiles npm Module

Since yFiles for HTML 2.2, the library comes as a npm module. This makes it easy to install it into your projects. Unfortunately, just running npm install --save yfiles won’t work, as yFiles is not published to the public npm registry because it is a commercial product.

This section presents some of your options for installing yFiles as a npm dependency.

Installing from the Local Filesystem

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

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

See yFiles Library Formats and Development Mode for more details on the individual variants.

To install one of the packages, simply run npm install with the path to one of these files:

> npm install --save <yFiles package path>/lib-dev/yfiles-26.0.0+local+dev.tgz

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

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

It is recommended to always depend on the .tgz file of the library.You could also provide the path to the extracted folder (i.e. es-modules/) as npm dependency instead. However, this is not recommended, as the latest versions of npm will then create a symlink in the node_modules folder, which might trip up some build tools and produce unexpected results.

Installing from a Remote Filesystem

When installing from your local filesystem, the path to the yFiles library has to be correct: Either you use a relative path and copy the yFiles package to the right place, or you use an absolute path and everyone has to use the same path. Both options are not that great.

This is where a central location comes in handy. Copy the .tgz archive of the yFiles library somewhere that is accessible by every machine that needs it, e.g. a NAS:

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

Then, you can install it from there and don’t have to worry about the path:

> npm install --save //my-nas/vendors/yfiles/yfiles-26.0.0+local+dev.tgz

Installing from a Local or Private npm Registry

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

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

Installing from a Local git Server

If you have a private/local git server, you can create a new repository there, then push the yFiles npm package there. Afterwards, you can install the yFiles dependency via a git link:

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

Note that you have to push the actual npm package to the repository, i.e. the extracted <yFiles package path>/lib-dev/es-modules folder, so that the package.json file resides top-level in the repository.

The Version Number of the yFiles npm Package

yFiles has always used a version number with 4 digits like 2.5.0.2. The first two digits signify the major version, the third is the minor version, and the last one is the bugfix level. To get a npm version number with 3 digits, the first two digits of the yFiles version are combined into the first digit of the npm package version, and the other two digits are kept. For example, the release 2.5.0.2 has the npm module version 25.0.2. This complies with Semantic Versioning.

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