Skip to content
Arc XP

Local environment and integration setup

This guide walks you through getting your local environment and integation set up for the first time.

Prerequisites

Local setup

Integration development is done locally first, and then deployed and promoted to sandbox and production later. Your integration should be fully tested before deploying to ensure no user workflows are broken.

In order to build and run integrations locally, Node.js version 22 is required. Use Node.js Version Manager (nvm) to install a specific Node.js version:

Terminal window
nvm install 22
# Check the installed node version
node -v
# Set the default version
nvm alias default 22

Download starter bundle

When you create a new integration, you are given a starter bundle. You can download it locally and begin coding. For more information, see Download a Bundle. We recommend managing your code with source control.

Install dependencies

Ensure package.json has the latest version of the IFX SDK. For example:

package.json
"dependencies": {
  ...
  "@arcxp/arcxp-ifx-node-sdk": "1.3.1"
  ...
 }

Create a GitHub token

Create a personal access token with read:package scope in your GitHub account. Please follow the instructions from here.

Install SDK

Once a GitHub token is created, there are two ways to install/download the IFX SDK. The first option is to create your local .npmrc file manually. Another option is to use npm login command.

Create .npmrc

This method seems to be the simplest. To create your local .npmrc file, first make sure you have a GitHub PAT ready.

Next, run each of the following commands:

Terminal window
export GITHUB_TOKEN=<your PAT generated through the GitHub console>
echo '@arcxp:registry=https://npm.pkg.github.com/' >> ~/.npmrc
echo '//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}' >> ~/.npmrc

Use npm command

To use npm login command:

Terminal window
npm login --scope=@arcxp --auth-type=legacy --registry=https://npm.pkg.github.com


# --- Username: your GitHub username
# --- Password: your PAT generated through the GitHub console https://github.com/settings/tokens
# --- Email: your GitHub email

Integration initialization

Once you are set up with npm and GitHub:

  1. From the project root run npm install

  2. If all succeeded, run npm run localTestingServer and you should see a message like:

    Terminal window
    > @myorg/myorg-myintegration@1.0.0 start
    > node node_modules/@arcxp/arcxp-ifx-node-sdk/localTestingServer

If you get errors such as “module not found”, from the root of the project run command rm -rf node_modules && npm install then run the local server again.

In the next article, we will practice creating event handlers that process events.


Have a feature request or suggestion? Let us know on Our Ideas Portal.