IRIS App Getting Started

Prerequisites

Before creating your first IRIS App, ensure you have the following in place.

1. Node.js Version 20 or Higher

The Magentrix CLI and the IRIS App project template both require Node.js.

• Download from nodejs.org — choose the LTS version
• Verify your installation by running:

node --version

You should see version 20.0.0 or higher.

2. Magentrix CLI Installed

Install the CLI globally so the magentrix command is available from any directory:

npm install -g @magentrix-corp/magentrix-cli

Verify the installation:

magentrix --version

To update to the latest version at any time:

npm install -g @magentrix-corp/magentrix-cli@latest

3. Access to a Magentrix Instance

You need a running Magentrix portal and the following:

• Instance URL — your portal address, for example https://yourcompany.magentrix.com
• API Key (Refresh Token) — obtain this from your Magentrix administrator or from your user profile in the portal settings

Step 1 — Configure CLI Credentials

From your Magentrix workspace directory, run the setup wizard:

magentrix setup

You will be prompted for your API key and instance URL. For CI/CD or scripted environments, use the non-interactive flags instead:

magentrix setup --api-key YOUR_API_KEY --instance-url https://yourcompany.magentrix.com

The CLI stores credentials per folder, so you can manage multiple Magentrix instances by running magentrix setup in different workspace directories.

Step 2 — Create a New IRIS App

Project Template

The official project template is the fastest way to get started. It includes pre-configured SDK integration, Vue 3 + TypeScript setup, Vite, and example components.

npm create @magentrix-corp/iris-app-template@latest my-app
cd my-app
npm install

Step 3 — Configure Your Project

Every IRIS App requires two configuration files in the Vue project root.

src/config.ts — App Metadata

export const config = {
	appSlug: "my-app",
	appName: "My Application",
	appDescription: "",
	appIconId: ""
}

The CLI searches for the config file in these locations in order: src/config.ts, config.ts, src/iris-config.ts, iris-config.ts.

.env.development — Environment Variables

VITE_SITE_URL = https://yourinstance.magentrix.com
VITE_REFRESH_TOKEN = your-api-key
VITE_ASSETS = '[]'

Step 4 — Link the Project to the CLI

From inside your Vue project directory, link it to the Magentrix CLI. This is a one-time step per project:

magentrix iris-app-link

The CLI registers your Vue project globally so it can be built and staged into any Magentrix workspace. You do not need to repeat this step unless you move the project folder or change the app slug.

Step 5 — Start the Development Server

magentrix vue-run-dev

This command fetches portal CSS assets from your Magentrix instance using VITE_REFRESH_TOKEN, writes them into VITE_ASSETS, and then starts the Vite dev server. Your app will be available at http://localhost:5173 (or the next available port) with full portal theming applied.

Project Structure

After setup, your Vue project will have the following structure:

my-app/
├── src/
│   ├── assets/              # Static assets (images, fonts)
│   ├── components/          # Vue components
│   ├── config.ts            # App metadata (appSlug, appName)
│   └── App.vue              # Root component
├── .env.development         # Local environment variables
├── package.json
└── vite.config.ts

Your Magentrix workspace — where server-side files live — has a separate structure:

magentrix-workspace/
├── src/
│   ├── Classes/             # Active Classes (*.ac)
│   ├── Controllers/         # Active Controllers (*.ctrl)
│   ├── Triggers/            # Triggers (*.trigger)
│   ├── Pages/               # ASPX pages (*.aspx)
│   ├── Templates/           # ASPX templates (*.aspx)
│   ├── Contents/
│   │   └── Assets/          # Static assets
│   └── iris-apps/
│       └── my-app/          # Built IRIS App bundle (staged here by CLI)
└── .magentrix/              # CLI configuration — do not edit

Your First Development Cycle

Daily Development

# From your Vue project directory
cd ~/my-app
magentrix vue-run-dev        # Start dev server with portal assets injected
# Make changes, review in browser at http://localhost:5173
# Press Ctrl+C to stop

Building and Publishing

# From your Vue project directory
magentrix vue-run-build      # Build and stage into the Magentrix workspace
# Prompted: "Do you want to publish to Magentrix now?" → Yes

After publishing, hard refresh your browser (Ctrl+Shift+R) on the portal to load the updated bundle.

What to Read Next