Licensing

Sell your app with license keys. The template integrates LicenseManager  with its Electron SDK : customers enter the key from their purchase email once, and the app checks it in the background from then on, online or offline.

• On launch, the app opens if the license is valid, and an activation window otherwise. It explains every problem (expired license, too many computers, version not included, offline for too long…) and what to do about it.
• If the license is refused while the app runs (it expired, or was revoked), the main window is replaced by the activation window. It comes back as soon as the license is valid again.
• The app keeps working offline for as long as your policy allows (one week by default), and warns the user before that time runs out.
• The auto updater only downloads the versions the license includes. When the newest version is not included, it downloads the latest one that is.
• The About window shows the license: the key with its end hidden and a copy button, its status, the offline time left and a link to manage it.

LicenseManager is free up to 100 active licenses, with no credit card required. See pricing  and plans and billing .

Set up your account

export const PRODUCT_ID = 'x7Kp2QaZ'
 
export const TEST_PRODUCT_ID = 't3Hw9LmB'
 
export const PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEA…
-----END PUBLIC KEY-----`
 
export const PURCHASE_URL = 'https://acme.com/buy'

Configuration

Everything is in src/main/license/config.ts:

The test and live products share the public key: the product id is what keeps TEST- keys from unlocking a release build. Packaged builds always use PRODUCT_ID (app.isPackaged decides, not something a customer can set).

The code lives in:

What the user sees

On launch

The SDK reads the stored key and the token saved by the last validation: a license signed by LicenseManager, valid for the max offline duration of the policy.

• A valid token: the main window opens right away, and the license is validated online in the background.
• A key but no valid token (e.g. first launch after the offline time ran out): the app validates online, retrying for up to 30 seconds. After 1.5 seconds, the activation window opens with “Checking your license…”, replaced by the main window once the license is validated.
• No key: the activation window asks for one.

The app is unlocked only in the ACTIVE state. Every other state shows the activation window, with a message and the actions that fix it. A new key can be entered in every state.

See License states .

Activation errors

Activating a key never changes the current state when it fails: the error is shown under the input.

Keys are case sensitive, and spaces around them are removed. A test key in a release build answers not_found. An invalid_response on every activation usually means a wrong PUBLIC_KEY or product id. See Activating a license .

The messages are in src/shared/locales/*/common.json, under license.

While the app runs

The SDK renews the token in the background, at two thirds of its lifetime, and validates again when the computer wakes up from sleep. When LicenseManager refuses the license (expired, deleted key, version no longer included), the main window closes and the activation window opens with the reason. When the license is fixed (Check again, a new key), the main window opens again.

Network failures, LicenseManager errors and plan limits never lock the app: it keeps running on its stored token.

The About window

About in the app menu (macOS) or the Help menu (Windows, Linux) opens a window with the app version and the license:

• Key: the beginning of the key, e.g. 7KQ2M-X9•••-•••••-•••••-•••••, and a button that copies the full key. The full key is copied by the main process and never sent to the renderer.
• Status: the license state.
• Verification: “Verified online”, or the time left to work offline and its date.
• Manage license: opens the customer portal.
• Check again: validates the license now.

It replaces the native macOS About panel. Edit src/renderer/src/routes/about.tsx to add credits or links.

Offline use

The app works offline until the stored token expires: the max offline duration of the policy after the last successful validation, or the license expiration if it comes first. When less than 3 days are left, a banner in the main window asks the user to connect to the internet. Change WARNING_MS in src/renderer/src/components/license-banner.tsx to warn earlier.

Offline, the SDK retries after 5 minutes, then waits twice as long each time, up to one hour. To guarantee more offline time after each renewal (e.g. for users who travel), pass minOfflineDurationMs to new LicenseManager() in src/main/license/index.ts.

An expired license, a deactivated machine or a shortened offline duration only reach the app when it validates online. See Working offline  and Clock tampering .

Updates

With licensing enabled, src/main/updater.ts changes the auto updater:

1. Updates are only checked while the license is active. Once the license is activated or fixed, it checks right away.
2. When a new version is found, the app asks LicenseManager if the license includes it, before downloading anything.
3. If it does, the update is downloaded and installed as usual.
4. If it doesn’t, LicenseManager answers with the latest version the license includes (latestAllowedVersion, among your recorded releases). If it is newer than the running version, the app downloads that one instead.
5. Otherwise, the main window shows “Version X is available, but your license doesn’t include it”, with a button to upgrade the license. Check for Updates… shows the same in a dialog.

If LicenseManager can’t be reached, nothing is downloaded: the next check (every 4 hours) tries again. If it refuses the license itself (expired, too many computers), the app validates the license and locks itself.

To check a version, the app calls the validate-key  endpoint with that version. A successful answer records it as the version of the machine in the dashboard, even before it is installed. It counts as one API request, like each validation.

Patch versions are never blocked: limits apply to the major and minor numbers (2.3). The app checks its own version on every validation too: a version installed by hand that the license doesn’t include shows VERSION_NOT_ALLOWED.

Protecting features

The windows follow the license, but code can always be called from the developer tools of a window. Features that require a license check it in the main process: use licensedProcedure instead of publicProcedure for their tRPC procedures. They throw a FORBIDDEN error while the license is not active. The todos of the template use it:

import { licensedProcedure, router } from '../trpc'
 
export const todosRouter = router({
  list: licensedProcedure.query(({ ctx }) => ctx.db.select().from(todos).all())
})

Elsewhere in the main process, call isLicenseActive() from src/main/license. It returns true when licensing is disabled.

Customers and computers

Each computer is identified by a fingerprint: a hash of the system machine id, combined with a random id stored on first launch. Reinstalling or updating the app keeps it. Reinstalling Windows or Linux, or a new computer, counts as a new machine. See Machine fingerprint .

When customers move to a new computer and reach their maximum, they deactivate the old one in the portal (Manage license), then click Check again. You can also deactivate machines from the Machines tab of the license in the dashboard, or raise its max machines.

To fix a license, open it in the dashboard: extend its expiration, change its updates or its max machines. The app picks up the change at its next validation, or right away with Check again. See Licenses  and Machines .

Testing

Use the test product to go through every state:

Updates can only be tested with a packaged app: see Auto Update.

The license is stored per product in the system keychain (service dev.licensemanager.sdk), and in files as a fallback. Uninstalling the app keeps it. To start over in development, delete it on macOS with:

for name in licenseKey licenseToken installId lastSeen; do
  security delete-generic-password -s dev.licensemanager.sdk -a "t3Hw9LmB:$name"
done
namespace=$(node -e 'console.log(require("crypto").createHash("sha256").update("dev.licensemanager.sdk:t3Hw9LmB").digest("hex").slice(0, 32))')
rm -rf ~/Library/Application\ Support/.$namespace ~/Library/Caches/.$namespace

Replace t3Hw9LmB with your test product id. Commands for Windows and Linux are in Stored data . Don’t ask customers to do this: it changes their fingerprint, so their computer counts as a new machine.

Packaging

The SDK stores licenses in the system keychain with @napi-rs/keyring , a native module installed by npm for the current platform and architecture only. Without it, the SDK falls back to files, silently.

• Install with npm install or npm ci, without --omit=optional.
• The release workflow builds two architectures on each macOS and Windows runner: its Install the keychain module for every architecture step adds the module of the other one.
• To check a build, activate a license in the packaged app, then look for dev.licensemanager.sdk in Keychain Access (macOS) or the Credential Manager (Windows).

Don’t need licensing?

If your app is free, or you sell it another way, you can leave licensing disabled: keep PRODUCT_ID or PUBLIC_KEY empty in src/main/license/config.ts. The app opens directly, updates are not gated, and the About window says licensing is not configured.

You can also remove the licensing code entirely, to keep the codebase and the app smaller. Nothing else in the template depends on it. Give this prompt to your coding assistant (Claude Code, Cursor, Codex…):

Remove licensing (licensemanager.dev) from this Electron app. Keep every other
feature working. Follow these steps:
 
1. Delete `src/main/license/`, `src/main/trpc/routers/license.ts`,
   `src/shared/license.ts`, `src/renderer/src/lib/license.ts`,
   `src/renderer/src/components/license-banner.tsx` and
   `src/renderer/src/routes/activate.tsx`.
2. In `src/main/trpc/router.ts`, remove the `license` router.
3. In `src/main/trpc/trpc.ts`, remove `licensedProcedure` and the
   `isLicenseActive` import. Replace every `licensedProcedure` with
   `publicProcedure` (e.g. in `src/main/trpc/routers/todos.ts`).
4. In `src/main/events.ts`, remove the `licenseChanged` event.
5. In `src/main/window.ts`, remove the activation window
   (`createActivationWindow`, `activationWindow`). `showAppWindow` and
   `focusAppWindow` only show and focus the main window. Remove the license
   from the comment of `showAboutWindow`.
6. In `src/main/index.ts`, remove `setupLicense`, `waitForLicense` and the
   `licenseChanged` listener: call `showAppWindow()` directly.
7. In `src/main/updater.ts`, remove the license gating: the license check,
   `checkVersionAllowed`, the fallback to the latest allowed version
   (`pinFeed`, `restoreFeed`, `readPublishConfig`, `pinned`), the
   `not-allowed` dialog and the `licenseChanged` listener. Set
   `autoUpdater.autoDownload = true` back, or call `downloadUpdate()` as soon
   as an update is available. Keep the "is up to date" and error dialogs of
   manual checks. Copy `compareVersions` here if it is still used.
8. In `src/shared/updater.ts`, remove the `license-required` and
   `not-allowed` states.
9. In `src/renderer/src/components/update-banner.tsx`, remove the
   `not-allowed` banner, `useLicense` and the `license` mutations.
10. In `src/renderer/src/routes/__root.tsx`, remove `<LicenseBanner />`.
11. In `src/renderer/src/routes/about.tsx`, remove the license section and its
    loader: the About window only shows the app name, logo and version.
12. In every `src/shared/locales/*/common.json`, remove the `license` and
    `duration` keys, `update.notAllowed`, and the license keys of `about`
    (keep `about.version`). Check no other code uses `duration.*`.
13. In `.github/workflows/release.yml`, remove the "Install the keychain module
    for every architecture" and "Record the release in LicenseManager" steps.
14. Uninstall `@licenseman/electron` with `npm uninstall @licenseman/electron`.
15. In `AGENTS.md` and `README.md`, remove the mentions of licensing,
    `license/` and `licensedProcedure`. In `.claude/skills/add-route/SKILL.md`,
    only mention `about.tsx` as an example of a standalone route.
16. Run `npm run dev` once to regenerate `src/renderer/src/routeTree.gen.ts`
    without the `/activate` route.
17. Search the codebase for `licen` (case-insensitive) to
    remove any leftover, then run `npm run check:fix` and `npm run typecheck`
    and fix every error.

Learn more

• Electron SDK , and its API reference 
• Validation and renewal 
• Renderer and IPC 
• Concepts : products, policies, licenses, machines, releases
• Desktop app guide  and trial licenses