Skip to content
Arc XP
Product Documentation

Using TypeScript and other JS Supersets in Integrations

Problem: Node.js is great, it is the gateway into the wide world of Javascript. That being said, we sure miss some type safety. Can we get some TypeScript support in IFX please?

Solution: Kind Of!

TLDR;

For the foreseeable future, IFX will expect Node.js/CommonJS code. The good news is that basically any JS superset can be transpiled into Node.js.

Long Version

Under the hood, IFX takes your bundled code and hands it off to AWS Lambda. For both AppSec and privacy reasons, as a rule we will no longer read, compile, build, or otherwise touch the code you upload. We use only AWS available runtimes which unfortunately does not currently include TS. Lambda runtimes - AWS Lambda →

Don’t fret, dear reader; This does not mean you can’t use TS with IFX, but it does mean there is an extra step.

The crux of IFX is this: You give us bundled Node.js code or Java jars, and we put them where they need to be to extend your Arc XP functionality. This means you can write something in CommonJS, Next, Node, Nuxt, Nest, heck even Scala.js if you’re feeling frisky. If you can transpile it to node in the expected directory structure, we will host it and we will like it!

On to the Tutorial

We’ve taken our sample repo and forked it so it could be TypeScriptified. The code has the same effect: print to the log when our custom handler is invoked due to an inbound event.

myHandlerOne.ts will be invoked when a story:create or story:update event appears.

myHandlerOne.ts
const myHandlerOne = (event: any) => {
  // Customer logic
  console.log(`my logic one`);


   return {
    "status": "event processed correctly",
    "payload": event
  }
}


export = myHandlerOne;

Pretty standard stuff compared to our Node sample repo. All we did was rename it from .js to .ts, and updated the export statement.

The magic all happens in tsconfig.json and package.json file. Lets dive in here:

tsconfig.json

tsconfig.json
{
  "compilerOptions": {
    "target": "es2016", /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
    "module": "commonjs", /* Specify what module code is generated. */
    "rootDir": "./", /* Specify the root folder within your source files. */
    "outDir": "./dist", /* Specify an output folder for all emitted files. */
    "esModuleInterop": true, /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables     'allowSyntheticDefaultImports' for type compatibility. */
    "forceConsistentCasingInFileNames": true, /* Ensure that casing is correct in imports. */
    "strict": true, /* Enable all strict type-checking options. */
    "skipLibCheck": true /* Skip type checking all .d.ts files. */
  }
}

The important bit here is that we have set our tsconfig.json to output everything during the transpile step to a dist folder. This is what will be bundled and uploaded via the IFX API.

package.json

The command localTestingServer will be able to take an optional argument in order to support testing the transpiled JS in the dist/ folder with the release of arcxp-ifx-node-sdk an upcoming release of the Node SDK.

package.json
{
  "name": "@myorg/myorg-myintegration",
  "version": "1.1.0",
  "engines": {
    "node": "18.13.0",
    "npm": "8.x"
  },
  "main": "index.js",
  "scripts": {
    "localTestingServer": "node node_modules/@arcxp/arcxp-ifx-node-sdk/localTestingServer ./dist",
    "clean": "rimraf dist/",
    "build": "npm run clean && tsc && cpy src/eventsRouter.json .env.sandbox .env.production ./node_modules/ ./dist",
    "zip": "(cd dist/ && zip -r ../dist.zip ./* -x \"dist.zip\")",
    "test": "echo \"No test specified\""
  },
  "dependencies": {
    "@arcxp/arcxp-ifx-node-sdk": "1.2.0"
  },
  "devDependencies": {
    "@types/node": "^20.4.8",
    "cpy-cli": "^5.0.0",
    "rimraf": "^5.0.1"
  }
}

Our package.json has some simple changes that should slip into your current workflow pretty painlessly. With a npm build zip command, the code will be:

  1. Cleaned up, remove any local artifacts
  2. “built” in the TS sense of the word, here is where we use the TS transpiler to output everything to be Node ready in the dist folder
  3. Zip everything up nice and neat for upload

With these changes, your workflow would look something like this: Dev changes → npm build zip → Upload → Deploy → Promote

From the command line:

Terminal window
npm build zip

Help us improve our documentation! Let us know if you do not find what you are looking for by posting suggestions to Our Ideas Portal.