Migrating FingerprintJS v4 to v5

This guide covers the changes required to upgrade your application from FingerprintJS version 4 to version 5.

License

The license for FingerprintJS v5 has changed from BSL 1.1 to MIT license. The MIT license enables you to

• Use FingerprintJS v5 for research / non-commercial purposes
• Use FingerprintJS v5 in production without a commercial agreement
• Fork and self-host FingerprintJS v5 in production

See the complete licensing statement in docs/licensing.md for additional details.

Installation

The migration process depends on the way you install the library.

CDN

Change the version number in the URL from 4 to 5. For example:

- https://openfpcdn.io/fingerprintjs/v4/iife.min.js
+ https://openfpcdn.io/fingerprintjs/v5/iife.min.js

NPM or Yarn

Update the package version:

npm install @fingerprintjs/fingerprintjs
# or
yarn add @fingerprintjs/fingerprintjs

JavaScript output and browser support

Updated compilation target

The distributed bundles are now compiled to ES2018 instead of ES5. Modern build tools already handle this target, but any pipeline that assumed ES5 output (for example, older minifiers or ES5-only runtime environments) may require updates to accept or transpile ES2018 syntax.

Supported browsers

The minimum browser versions officially supported by FingerprintJS are listed in the browser and device support guide. Confirm that the browsers you rely on meet or exceed these versions before deploying v5.

Transpiling to ES5 when required

If you must keep ES5-compatible artifacts—for example, when embedding FingerprintJS into legacy applications—you now need to run that transpilation yourself. A typical setup using Babel might look like:

// babel.config.json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "ie": "11"
        },
        "useBuiltIns": "usage",
        "corejs": "3.38"
      }
    ]
  ]
}

Or, if you compile with TypeScript, adjust your tsconfig.json:

{
  "compilerOptions": {
    "target": "ES5",
    "downlevelIteration": true
  }
}

Make sure that your bundler (Webpack, Rollup, Vite, etc.) picks up these settings so that the FingerprintJS package is transpiled along with your application code.

For Webpack with babel-loader, explicitly include the library so it is processed despite the default node_modules exclusion:

// webpack.config.js
module.exports = {
  // ...
  module: {
    rules: [
      {
        test: /\.m?js$/,
        exclude: /node_modules\/(?!@fingerprintjs\/fingerprintjs)/, // this will transpile FingerprintJS
        use: {
          loader: 'babel-loader',
          options: {
            presets: [
              [
                '@babel/preset-env',
                {
                  targets: { ie: '11' },
                  useBuiltIns: 'usage',
                  corejs: '3.38'
                }
              ]
            ]
          }
        }
      }
    ]
  }
}

If you use TypeScript, ensure that the bundler reads your tsconfig.json (for example via ts-loader or babel-loader with @babel/preset-typescript) so that the downlevel settings apply to both your code and FingerprintJS.

API

Turning off the monitoring

When the load function runs, there is a 0.1% chance of sending a request. The requests are sent at most once a week from one browser instance (unless the browser cache was cleared). A request includes the following information:

• The library version
• The HTTP headers that the client sends, including the origin and the referrer of the page where the library runs
• The IP of the client

You can turn off these requests by using the monitoring option:

const fpPromise = FingerprintJS.load({
+ monitoring: false
})

💡 Scripts downloaded from our CDN (https://openfpcdn.io) have monitoring disabled by default.