Skip to main content

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+ support later this year)

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:

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

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

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

Change your webpack config​

Headlockr requires a slight modification in your webpack configuration file. Located at src/admin/webpack.config.js. In case your file is named webpack.config.example.js please rename it to webpack.config.js.

warning

Headlockr currently only supports Webpack and not the newest Vite compiler. This is on our roadmap for 2025.

const HtmlWebpackPlugin = require("html-webpack-plugin");
const writeHeadlockrClientFiles = require("@headlockr/headlockr/client");

module.exports = (config) => {
  config.plugins = config.plugins.map((plugin) => {
    if (plugin instanceof HtmlWebpackPlugin) {
      return new HtmlWebpackPlugin({
        template: ".headlockr/client/index.html",
        inject: true,
      });
    }
    return plugin;
  });

  config.entry.main.push("./.headlockr/client/headlockr-admin-panel.tsx");

  config.plugins.push({
    apply: (compiler) => {
      compiler.hooks.beforeRun.tapPromise(
        "GenerateHeadlockrFiles",
        async () => {
          console.log("Generating Headlockr runtime files...");

          await writeHeadlockrClientFiles({
            runtimeDir: ".headlockr/client",
            logger: console,
          });

          console.log("Headlockr runtime files generated successfully.");
        }
      );
    },
  });

  // Important: return the modified config
  return config;
};

🎉 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.