Installation and setup

Install

npm install @licenseman/electron

pnpm add @licenseman/electron

yarn add @licenseman/electron

electron 28 or later is a peer dependency. The package also installs @napi-rs/keyring as an optional dependency, a native module the SDK uses to reach the system keychain: see packaging.

Create the LicenseManager

import { app } from "electron";
import { LicenseManager } from "@licenseman/electron";
 
const PRODUCT_ID = "x7Kp2QaZ";
const PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEA…
-----END PUBLIC KEY-----`;
 
let license: LicenseManager;
 
app.whenReady().then(async () => {
  license = new LicenseManager({ productId: PRODUCT_ID, publicKey: PUBLIC_KEY });
  license.onStateChange((state) => sendStateToWindows(state));
 
  const state = await license.ready();
  if (state === "ACTIVE") openMainWindow();
  else openActivationWindow();
});

app.on("will-quit", () => license?.dispose());

What happens on construction

The constructor returns right away, and starts in the background:

1. It reads the stored key. No key: the state becomes MISSING_KEY before the constructor returns, and ready() resolves with it.
2. With a key and a valid stored token, the state becomes ACTIVE, and ready() resolves with it right away. The online validation runs in the background: when it refuses the license, the state changes, and your listener is called.
3. With a key but no valid stored token, it validates the key online, retrying for up to 30 seconds, and ready() resolves once it’s done, with ACTIVE or the reason the app is locked.
4. It starts the clock check, now and every hour.

The constructor throws only when productId or publicKey is empty. Everything else, a missing keychain, no network, a broken fingerprint command, is handled without throwing.

One instance per product

Treat the LicenseManager as a singleton. Two instances with the same productId share the same stored data, but not their state or timers: they’d both validate in the background, and could disagree after one of them activates a new key.

An app selling several products, like an app and a paid plugin with their own licenses, creates one instance per product, each with its own productId. Their keys, tokens and fingerprints are stored separately and never overlap.

Options

new LicenseManager({
  productId: "x7Kp2QaZ",           // required
  publicKey: PUBLIC_KEY,           // required
  version: "2.3.1",                // default: app.getVersion()
  machineName: "Jane's MacBook",   // default: the hostname
  platform: "macOS",               // default: macOS, Windows or Linux
  fingerprint: () => readMyId(),   // default: the system's machine id
  minOfflineDurationMs: 3 * 24 * 60 * 60 * 1000, // default: 0
});

version

By default, it’s Electron’s app.getVersion(), the version of your app’s package.json. Two cases to know:

• In development, when your package.json has no version, app.getVersion() returns Electron’s version, like 33.2.0, which can be refused with version_not_allowed. Set a version in package.json, or pass version.
• Outside Electron, like in unit tests run by Node.js, there’s no app: pass version, or every validation fails. In setLicenseKey, it throws version is required when not running in Electron; in the background, it’s handled like a network error.

machineName and platform

Both are sent with every validation, and replace what LicenseManager knows about the machine. The hostname often holds the customer’s name, like Janes-MacBook-Pro.local, which is what makes machines easy to recognize in the customer portal. Pass your own value if you’d rather not send it.

Development and release builds

Point your development builds at a test product, and your release builds at the live one. Both share the same public key, which is one per organization:

const PRODUCT_ID = app.isPackaged ? "x7Kp2QaZ" : "t3Hw9LmB";

A test key validated against the live product answers not_found, and the opposite too: the SDK shows INVALID_KEY.

Packaging

The keychain is reached through @napi-rs/keyring, a native module. When it can’t be loaded, the SDK silently falls back to files: your app keeps working, but the key and token are less protected. Check these when you package your app:

• Keep it in your dependencies. Don’t install with --no-optional, or --omit=optional: it’s an optional dependency.
• Install it for each target. It ships one binary per system and architecture, like @napi-rs/keyring-darwin-arm64, and your package manager only installs the one of the computer it runs on. Build each platform on its own system, like with one CI job per platform, or install the binaries of the platforms you target. For a universal macOS app, you need both darwin-arm64 and darwin-x64.
• Unpack it from the asar archive. Native modules can’t be loaded from inside app.asar. electron-builder unpacks them by default; with Electron Forge, add @electron-forge/plugin-auto-unpack-natives.
• Don’t bundle it. If you bundle your main process with Vite, webpack or esbuild, mark @napi-rs/keyring as external: the SDK loads it with require at runtime, and a bundler that can’t see it leaves it out, without an error.

To check it works, activate a key in your packaged app, then look for items of the service dev.licensemanager.sdk in the Keychain Access app on macOS, or the Credential Manager on Windows.

Network access

The SDK makes two kinds of requests, from the main process, with Node’s fetch:

Requests from the main process don’t go through your windows’ Content Security Policy. They don’t go through the proxy configured in Chromium either: on a network that only allows traffic through a proxy, they fail, and the SDK handles it like being offline.