# Local environment and integration setup

Source: https://dev.arcxp.com/integrations/manage-integrations/integration-setup/

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

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

## Prerequisites

- You have [created an integration](https://dev.arcxp.com/integrations/manage-integrations/create-and-manage-integrations/)

## Local setup

Integration development is done locally first, and then [deployed and promoted](https://dev.arcxp.com/integrations/bundles/bundle-deployment-workflow/#deploy-a-bundle) 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](https://heynode.com/tutorial/install-nodejs-locally-nvm/) (nvm) to install a specific Node.js version:

Terminal window

```bash
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](https://dev.arcxp.com/integrations/bundles/bundle-deployment-workflow#download-a-bundle). We recommend managing your code with source control.

## Install dependencies

Ensure `package.json` has the latest [version of the IFX SDK](https://github.com/arcxp/arcxp-ifx-node-sdk/pkgs/npm/arcxp-ifx-node-sdk). For example:

package.json

```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](https://docs.github.com/en/enterprise-server@3.4/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).

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

```bash
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 the npm login command:

Terminal window

```bash
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  
```bash
> @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.

|          |                                                                                               |
| -------- | --------------------------------------------------------------------------------------------- |
| Default  | npm run clean && cpy src/\* .env.sandbox .env.production ./node\_modules/ ./dist              |
| Modified | npm 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`.

|          |                                                                                                  |
| -------- | ------------------------------------------------------------------------------------------------ |
| Default  | n/a                                                                                              |
| Modified | nodemon --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

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

module.exports = {
  firstHandler,
  secondHandler,
}
```

> **Caution:**
> 
> If you remove the `prelocalTestingServer` script and manage `src/eventsHandlers.js` yourself, make sure you keep that file up to date whenever you add, remove, or rename handlers.

---

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](https://ideas.arcxp.com/?project=IFX).