Skip to main content
Version: 5.x

Installation

info

Before installing Headlockr, the following requirements must be installed on your computer:

  • Node.js: Only Active LTS or Maintenance LTS versions are supported (currently v18 and v20). Odd-number releases of Node, known as "current" versions of Node.js, are not supported (e.g. v19, v21).
  • Your preferred Node.js package manager:
    • npm (v6 and above)
    • yarn
    • [strapi] Headlockr works on Strapi v4.16.0 and above (v5+ is supported in Headlockr v4.x.x)

Install the Headlockr package with npm/yarn​

Download (from your Headlockr portal account) or configure a .npmrc file or .yarnrc.yml file and place it in the root of your Strapi project. This file provides you permissions to pull the Headlockr library from our private npm proxy. If you do not have a license code yet, please claim one first via https://headlockr.io/#pricing. Without a license Headlockr won't work and you won't be able to install it.

Create .yarnrc.yml or .npmrc in your Strapi root folder:

Add .npmrc file​

@headlockr:registry=https://headlockr.nodejs.pub
//headlockr.nodejs.pub/:_authToken=YOUR-LICENSE-KEY-HERE
always-auth=true

Add License key​

Add the license key that you received by email into the .env file.

HEADLOCKR_LICENSE_KEY=enter-your-license-key-here

Install the plugin dependencies​

Next, run the install command by using the correct scope and package name:

npm install @headlockr/headlockr @tanstack/react-query@^5.56.2

Headlockr 5.0.0 breaking change​

warning

If you install or upgrade to Headlockr 5.0.0 or newer, remove the old Headlockr-specific admin build setup from your project.

  • Remove old customizations from src/admin/vite.config.js or src/admin/webpack.config.js
  • Remove imports such as @headlockr/headlockr/vite, @headlockr/headlockr/client, headlockrPlugin, or writeHeadlockrClientFiles
  • Remove any generated runtime wiring that previously targeted .headlockr/client or .strapi/client

Headlockr now integrates more cleanly with Strapi natively. These exports are no longer part of Headlockr 5.0.0+ and no extra Vite or Webpack integration is required anymore.

Next step​

Continue with the default configuration guide to configure your license key, passkeys, trusted devices and the rest of the plugin settings.

🎉 Congratulations! You have just installed Headlockr into your Strapi project. The next chapter will guide you through the process of how to configure Headlockr, how to add your license code and to get it up in running within in your Strapi instance.