Skip to main content

Version: 24.04

Installation

For those comfortable with the JavaScript ecosystem, installing the tools required for Open UX development will be a familiar process.

Prerequisites​

  1. Before installing the Open UX CLI, ensure that Node.js LTS version 18 (a minimum of 18.18 version is required) is installed on your system. For information about installing Node using a package manager (on Linux and other operating systems), see Installing Node.js via package manager. For Unix-based systems, make sure you are logged in as a user with sudo privileges. Once Node is installed, you can access the npm command to install Open UX packages from Artifactory.

  2. Access to a Journey Manager instance with privileges enough to deploy forms.

  3. Account access and sufficient permissions for https://internal-artifactory.avoka.com/artifactory/api/npm/npm/ to install the @transact-open-ux/analytics package

info

Yarn is an alternative to NPM that downloads packages from the same repository but offers a range of benefits over NPM. Throughout this documentation, examples are provided for both NPM and Yarn.

Installing the Open UX CLI​

The Open UX CLI is a command-line utility for creating, managing, and deploying Open UX projects.

note

You must obtain your own Artifactory credentials to complete this step.

In the command line or terminal, run the following commands:

  1. Set the default npm registry for Open UX scoped packages.

    npm config set @transact-open-ux:registry https://internal-artifactory.avoka.com/artifactory/api/npm/npm/

  2. Authenticate the npm client to Artifactory.

    npm login --registry https://internal-artifactory.avoka.com/artifactory/api/npm/npm/

    This command prompts you to press Enter then log into Artifactory in the browser with your username and password. Once authenticated in the browser you can return to the command line.

  3. Verify your ~/.npmrc file has content similar to the following:

    @transact-open-ux:registry=https://internal-artifactory.avoka.com/artifactory/api/npm/npm/
    //internal-artifactory.avoka.com/artifactory/api/npm/npm/:_authToken=<_authToken>

  1. Install the @transact-open-ux/cli package globally.

    npm install --global @transact-open-ux/cli

    Regardless of whether you use npm or Yarn, ensure you specify the global option so that the command is available across your operating system and not restricted to a specific directory.

To verify that the installation was successful, open the command line application on your computer and run the transact command. This displays the list of options transact accepts.

Usage:  <command> [options]

Options:
  -V, --version                      output the version number
  -h, --help                         output usage information

Commands:
  create [options] [directory-name]  create a new transact-open-ux application
  deploy [options]                   deploys app to Journey Manager
  mock [options]                     provides Open UX API mocking via running an express server

  Run transact <command> --help for detailed usage of given command.

Installing an Open UX library​

The Open UX CLI provides tools for managing projects, but to develop with it you'll need to install at least one library that contains the API calls for interacting with Journey Manager.

Two libraries are available:

  • Core: @transact-open-ux/core
  • React: @transact-open-ux/react

The Core library contains the essential elements for working with the Journey Manager API. If you create a project with the transact create command, this library is installed automatically. To install it manually, see Open UX Core Library.

The React library is a higher-level library for React developers. It contains components that abstract away many of the lower-level details. If you create a project with the React template, this library is installed automatically. To install it manually, see Open UX React Library.