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+ 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

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 is currently still supporting Webpack but will deprecate this in the future. The default for Strapi v5 is the Vite compiler and is advised to be used

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;
};

Or use Vite (Experimental)​

Headlockr now offers experimental Vite support for advanced users. While full integration is under development, you can already use Headlockr with Vite-based admin panels. Please note this is not yet officially stable.

If your Strapi project uses Vite instead of Webpack for the admin panel, you can configure Headlockr using the following setup.

Prerequisites

  • Strapi v5.16.0 or later
  • Vite-based admin build (customized manually)
  • Headlockr v4.1.3 or above
  • Node.js v18 or v20
  • A valid Headlockr license key

Customize your vite.config.js file with the code below. The file is located at src/admin/vite.config.js.

warning

Please make sure to rename the automatically generated src/admin/vite.example.js file to vite.config.js|ts

const { mergeConfig } = require("vite");
const path = require("path");
const { headlockrPlugin } = require("@headlockr/headlockr/vite");

module.exports = async (config) => {
  const runtimeDir = path.join(process.cwd(), ".strapi", "client");
  const entryFile = path.join(runtimeDir, "headlockr-admin-panel.tsx");

  return mergeConfig(config, {
    resolve: {
      alias: {
        "@": "/src",
      },
    },
    build: {
      rollupOptions: {
        input: {
          headlockr: entryFile,
        },
      },
    },
    css: {
      preprocessorOptions: {
        scss: {
          quietDeps: true,
        },
      },
    },
    plugins: [
      headlockrPlugin({
        runtimeDir,
        logger: console,
      })
    ],
  });
};

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