About

This boilerplate code simplifies setting up and managing ArcXP IFX in an imperative way. It comes with standard commands to manage your integrations, deliver your code, and utilities for faster development.

You can start a new project by forking this repository directly. Alternatively, copy the code into a new repo and later add this boilerplate as a remote to stay in sync. To sync changes from the boilerplate, run:

git remote add boilerplate https://github.com/code-store-platform/arcxp-ifx-boilerplate.git
git fetch boilerplate
git merge boilerplate/main

---

Project Structure

• ./integrations/ – All integrations live here.
• ./packages/commands – Command implementations.
• ./packages/shared – Shared utilities (logger, ArcAPI, etc).
• ./packages/tsconfig – Centralized TypeScript configs.

---

Setup

Prerequisites

• Node.js 22.x or higher.
• pnpm 8.x.
• Run pnpm install to install all dependencies.
• Create .env.sandbox from .env.example and fill in required values
• Create .npmrc by duplicating .npmrc.example and updating the necessary values.

---

Creating a New Integration

1. Run:

   pnpm ifx init

   • Creates a new integration folder under ./integrations/.
   • Installs dependencies and provisions it in IFX.

2. Add event handlers:

   • Implement handlers in eventsHandlers/ and export them in eventsHandlers.ts.
   • Wire them up in eventsRouter.json.

3. Deploy:

   pnpm ifx deploy

4. Update IFX definition:

   pnpm ifx provision

Example handler: ./integrations/hello/src/eventsHandlers/example.ts.

---

Commands

General

• Commands default to the sandbox environment. Use --env production for production.

• Integration commands require --integration:

  pnpm ifx <command> --integration my-integration

---

Available Commands

pnpm ifx init

Initialize a new integration.

pnpm ifx provision

Create or update the integration in IFX using ifx-definition.yml.

pnpm ifx deploy

Build and deploy the integration bundle to IFX.

pnpm ifx build

Build the integration and validate with the health handler.

pnpm ifx promote

Promote a deployed bundle to LIVE.

pnpm ifx destroy

Delete an integration.

pnpm ifx logs

Show latest logs for integrations.

pnpm ifx status

Show detailed integration information (bundles, subscriptions, secrets, etc).

pnpm ifx list_events

List all custom events.

pnpm ifx list_webhooks

List all webhooks.

pnpm ifx list_subscriptions

List all event subscriptions.

pnpm ifx create_event

Create a custom event.

pnpm ifx create_event --name my_event --description "My custom event"

The custom: prefix is added automatically if omitted.

pnpm ifx create_webhook

Create a webhook for a custom event.

pnpm ifx create_webhook --event my_event --description "My webhook"

Returns the webhook URL generated by Arc XP. Use this URL with a restricted IFX token to trigger the webhook.

pnpm ifx dev

Run the integration locally in watch mode.

• Default: random port.
• Override with PORT env.

Example request:

curl --location 'http://localhost:54265/' \
--header 'Content-Type: application/json' \
--data '{
  "key": "story:create",
  "body": { "id": "test" }
}'

---

Notes

1. Always specify --env (sandbox or production) when needed.
2. Use --integration <name> for all integration commands (required).

---

Happy Developing 🎉

This CLI streamlines the workflow for managing ArcXP IFX integrations.