Tech Blog

Installing AEK 2 in 2021

AEK 2 was first released in 2016, designed for Node v8 (and React v13). Over the years we’ve updated it (to target Node v10, and React v15, and later React v16). With these changes came changes to the underlying technologies (swapping out npm for Yarn, for example). These third-party packages aren’t something we can maintain ourselves, and over the years we’ve noticed specific issues on a range of machines when installing AEK 2 for the first time.

This blog post aims to provide an up-to-date overview of how to manage your versions of Node.js and install and use AEK 2 with them.

Node versions and the AEK

The AEK is still intended to be used with Node 10 (any release, though generally the latest is the best). Past releases of Node.js can be found here on their site. For reference, the latest versions of 10 and 12 (currently) are listed below.

Note – there is a known issue with aek install on Node 10 (any version of Node 10). This can also be seen when doing aek pull or aek create, as these commands both use aek install internally. We currently don’t have a fix implemented for this issue, but if you re-run the install command with the following argument, it will work: aek install --ignore-engines. This is due to a Node dependency no longer being officially supported for Node 10.

Alternatively, you can run aek install on the package in question under Node 12. The link to the latest version of Node 12 can be found here:

All other aek commands work with Node 10, and may have issues on Node 12. We recommend you stick with Node 10 for your daily AEK work, unless you’re running aek install.

Node 12 is replacing Node 10 on my machine!

Normally you can’t have more than one version of Node.js installed at a time. There is a utility on Windows we recommend for this called nvm-for-windows, or Node Version Manager for Windows (for Mac and other operating systems, there is nvm). Please follow the instructions in the README.md to set it up. It requires you to completely uninstall your existing Node.js version (if you have any installed).

Once you have nvm-for-windows installed, you can keep on adding different Node versions and switching between them as required. Please note that switching Node versions may affect how a project works on your machine. The Node versions are completely separate, with separate global packages and configuration.

Installing the AEK

Before you try to install the AEK CLI, please do the following:

  1. Use NPM config to link the @ombiel name-spaced packages: npm config set @ombiel:registry https://npm.campusm.net/.
  2. Check the config with npm config list. You should see @ombiel:registry = "https://npm.campusm.net/" in the list. If you don’t, see “Issues setting NPM config”, below.
  3. Install Yarn: npm install -g yarn.
  4. Check you have gulp-cli installed. You can test this in a terminal program with gulp -v.
  5. If gulp isn’t recognised as a program, or your CLI version is “Unknown”, install it with yarn global add gulp-cli.
  6. You can then use Yarn to install the CLI: yarn global add https://npm.campusm.net/get/aek-cli.

This should be enough in most cases to get the AEK up and running.

Reminder – you will need to repeat most of this process for each version of Node that you have installed. So if you have both Node 10.24.1 and Node 12.22.5 installed, you will need to link the config twice, and install Yarn twice.

Note – while nvm-for-windows handles global npm packages, Yarn’s installation of the AEK will be global – across all versions of Node you have installed.

Issues setting NPM config

Depending on your version of npm and your terminal program of choice, the config in step 1 of “Installing the AEK” might not work properly. The first thing you should try is wrapping @ombiel:registry in double quotes, so the command becomes npm config set @ombiel:registry https://npm.campusm.net/.

If that doesn’t work (checking with npm config list), try replacing a space between the two values with an equals. The command becomes npm config set @ombiel:registry=https://npm.campusm.net/.

As a last resort before opening something like a Salesforce case, or checking our Slack #aek channel, try combining the two approaches. We don’t recommend this by default as it seems to be dependent on the software you’re using. We’ve also tested the original command (no double quotes, no equals) on both Windows 10 and Windows 11, in Command Prompt, PowerShell and Terminal, and the only combinations that seemed to give the team any issues were PowerShell and Terminal on Windows 10.

Windows users

On Windows, you might still have a problem when running the aek command from the command line. It will tell you that “aek is not recognised as an internal or external command”. This is due to an issue with installing Yarn modules globally. If you encounter this, follow the steps below:

  1. Check if your yarn prefix is set with yarn config get prefix, in a terminal program of your choice.
  2. If it isn’t set, set it to the parent directory of the following command: yarn global bin.
    1. It’ll look something like C:/Users/<USER>/AppData/Local/Yarn (by default).
  3. Use yarn config set prefix FILEPATH to do this (where FILEPATH is the directory we found on the line above).
  4. Add the actual bin to your system PATH with set PATH=%PATH%;FILEPATH.
    1. You can also do this via “Edit the system environment variables”, which can be found under System in Control Panel, or by searching for “environment variables” in the Start Menu.
  5. Restart your terminal program (be it cmd, PowerShell, or something different) and try aek again.
  6. If it still doesn’t work, add the parent directory from step 2 to your system PATH as well (again, this can be done using the Control Panel instead of a terminal).

Additional reading

Leave a Reply