Upgrading

KeyLines versioning

It’s worth understanding the difference between major and minor KeyLines versions, because it affects the steps you should take before you upgrade. We use a format similar to semantic versioning, where releases are numbered in the format major.minor:

• Major versions (e.g., x.0) are released roughly once a year. In exceptional cases, they may contain breaking changes.
• Minor versions (e.g., x.1, x.2, etc.) are released regularly throughout the year. They contain backwards-compatible features and fixes.

Multiple licenses

If you have KeyLines licensed for multiple projects, always make sure you're logged into the correct project. Every time you log in, you will be prompted to select the appropriate project. The project name, and where applicable the expiry date, are then shown at the top of the screen while you are visiting the site.

To switch between projects, log out and select the correct project when you log back in.

License expiry

Your KeyLines download may have an expiry date. To avoid being locked out, ensure a renewal process is in place before the license expires. For more information see License Renewal.

You should also make sure that when you renew, you log out and select your new license when you log back in to continue using KeyLines.

Before you upgrade

It's important to read the Release Notes for details of new and updated features, enhancements, and bug fixes. Also check the deprecated items that we plan to stop supporting in the next major release. You can check the details of your current version using KeyLines.info() to work out what's changed.

Before you upgrade to a major version, it’s also important to check for:

• Breaking changes
• End of support notices in the Release Notes

If you can’t upgrade to the latest major version right away, you can always use a Long Term Availability (LTA) release.

How to upgrade

If you need help upgrading, contact [email protected].

If you have installed KeyLines 6.10 or later using our instructions for JavaScript, Angular, React, Vue, Webpack or Rollup, you have installed KeyLines as a npm package using keylines.tgz, which is our recommended installation method.

To upgrade your package to the latest version, or to update your license, follow the steps below:

Step 1: Download the package

Download the KeyLines package from the link below and move it to your project directory, removing any older keylines.tgz packages. Do not change the file name.

Step 2: Install the package

Using your preferred package manager, remove the old version and install the package again from inside your project's directory:

npm uninstall keylines
npm install file:./keylines-8.6.0-11643712880.tgz

yarn remove keylines 
yarn add ./keylines-8.6.0-11643712880.tgz

pnpm remove keylines 
pnpm install file:./keylines-8.6.0-11643712880.tgz

Step 3: Verify the upgrade

To verify the upgrade was successful, run the following command from inside your project's directory:

node -p 'require("keylines").info()'

Before you deploy to production, run your compatibility tests in a developer environment.

Legacy installations - for applications using keylines.js

If you are using KeyLines 6.9 or earlier, you have most likely installed KeyLines as a UMD bundle by referring to keylines.js.

This is now a legacy installation method and we recommend following our instructions for JavaScript, Angular, React, Vue, Webpack or Rollup to install KeyLines as a npm package.

If you want to keep using keylines.js and need to upgrade to the latest version or update your license, follow these steps to overwrite your existing files with the new versions:

1. First, download the latest KeyLines package.
2. Unpack the keylines.tgz archive. You can read more about this format and how to unpack it in the File Format Database.
3. Locate the keylines.js file in the unpacked archive. This should be located in keylines-8.6.0-11643712880/js/.
4. Go to your project directory and replace your old keylines.js file with the new one.
5. If you're using KeyLines with Leaflet or using PDF export, third-party resources are no longer included in the KeyLines bundle. Any required files are listed in the Leaflet Integration and PDF Export documentation.
6. To verify the upgrade was successful, you can call KeyLines.info() to show information about your KeyLines environment.
7. Run your compatibility tests in a developer environment before you deploy to production.

Troubleshooting

If you need help upgrading, contact [email protected].

Console error: Cannot find namespace 'KeyLines'

If your TypeScript uses a KeyLines namespace you could see this compilation error. For example:

// Error: Cannot find namespace 'KeyLines'
function labelValue(label: KeyLines.LinkEndLabel) {}

This is because prior to version 6.10 KeyLines came as a UMD bundle with a global variable and namespace 'KeyLines'.

KeyLines versions 6.10 and later come with both UMD and ESM bundles, and the TypeScript declaration has changed to make these bundles compatible with each other.

Below are some suggestions how to fix this compilation error:

Use a wildcard import

One way to fix the compilation error is to introduce a wildcard import at the top of your file to import KeyLines types:

import KeyLines, * as kl from "keylines";

And then later in the same file you can refer to this wildcard:

function labelValue(label: kl.LinkEndLabel) {}

You can read more in the Using KeyLines type definitions section of our TypeScript documentation.

Continue using keylines.d.ts

If you don't need to access the latest KeyLines type definitions, you can avoid this issue by continuing to use the keylines.d.ts TypeScript declaration file that was used prior to version 6.10.

This file will be forward compatible with newer releases until the next major version.

Blank chart / "License Expired" persist after license upgrade

If you are upgrading KeyLines after your license or your evaluation version had expired, downloading the latest version from the Download page and installing it should reinstate the chart / remove the "License Expired" watermark.

If it doesn't, try clearing the package manager's cache and installing the package again:

npm cache clean --force
npm install file:./keylines-8.6.0-11643712880.tgz

yarn cache --clean
yarn add ./keylines-8.6.0-11643712880.tgz

# step not required for pnpm