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.

Customizing the scripts in package.json

Your starter bundle includes a working package.json you can use as-is, but you can tailor it to match your tools and CI/CD. Keep the Node.js version aligned with the documentation and ensure the IFX SDK dependency stays current.

You can modify any scripts in package.json — to fit your team’s workflow. The examples below show a few common patterns, but you can change or extend any scripts you want.

build

Including package.json in your build makes the bundle self-contained — other developers can simply download the compiled folder, install dependencies, and start the integration locally without reconfiguring anything.

Defaultnpm run clean && cpy src/* .env.sandbox .env.production ./node_modules/ ./dist
Modifiednpm run clean && cpy src/* .env.sandbox .env.production ./node_modules/ package.json ./dist

watch

If you want your local environment to automatically rebuild whenever source files change, add a watch script using a tool like nodemon.

Defaultn/a
Modifiednodemon --watch src --exec \"node node_modules/@arcxp/arcxp-ifx-node-sdk/localTestingServer\"

Dependencies will require: "nodemon": "^3.1.10",

prelocalTestingServer

The starter bundle includes a prelocalTestingServer script that runs before your local server starts. It simply auto-generates the src/eventsHandlers.js file used by the IFX SDK. You don’t have to use it — if your handlers are stable or you prefer to manage them manually, you can maintain that file yourself.

You can either start by running npm run localTestingServer to generate the file, or you can create it yourself. Its contents should include each handler’s name and filepath:

src/eventsHandlers.js
const firstHandler = require('./eventsHandlers/firstHandler');
const secondHandler = require('./eventsHandlers/secondHandler');


module.exports = {
  firstHandler,
  secondHandler,
}

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.