Iris App Template

A Vue 3 + TypeScript template for creating custom Iris applications with module federation support for the Magentrix ecosystem.

Features

• ⚡️ Vue 3 with Composition API and <script setup> syntax
• 🔷 TypeScript for type-safe development
• ⚙️ Vite for fast development and optimized builds
• 🔌 Module Federation for microfrontend architecture
• 🛣️ Vue Router for single-page application routing
• 🎯 Dynamic Mounting with configurable base paths
• 🎨 Tailwind CSS 4.1 for utility-first styling

Getting Started

⚠️ Important: Use the Template Command

Do NOT install this repository directly. Instead, use the template creation command:

npm create @magentrix-corp/iris-app-template@latest

Follow the prompts to enter your project name and configuration.

Step 1: Configure Environment Variables

After creating your project, navigate to the project directory and configure your local development environment:

cd your-project-name

Open .env.development and update it with your Magentrix portal credentials:

VITE_SITE_URL=https://your-portal.magentrix.com
VITE_REFRESH_TOKEN=your-refresh-token-here

Important:

• VITE_SITE_URL: Your complete Magentrix portal URL (must include https://)
• VITE_REFRESH_TOKEN: Your authentication token for local development
• Never commit .env.development to version control (it's already in .gitignore)

Step 2: Configure Application Settings

Open src/config.ts and populate the application configuration:

export const config = {
  appSlug: 'your-app-slug',          // REQUIRED: URL-friendly slug (no spaces or special characters)
  appName: 'Your App Name',          // REQUIRED: User-friendly display name
  appDescription: 'App description', // OPTIONAL: Brief description of your app
  appIconId: 'icon-id',             // OPTIONAL: Icon identifier for the app
}

Required:

• appSlug: Must be URL-friendly (e.g., my-custom-app, sales-dashboard)
• appName: Display name shown to end users in navigation menus

Optional:

• appDescription: Brief description of what your app does
• appIconId: Icon identifier for your app in the Magentrix portal

Important:

• appSlug must match the name property in package.json
• appSlug is used in the build output path: /contents/iris-app/{appSlug}/

Step 3: Install Dependencies

Install the project dependencies:

npm install

Step 4: Start Development

Start the local development server using the Magentrix CLI command:

magentrix vue-run-dev

This command:

1. Validates the assets reference in .env.development based on your site URL
2. Starts the Vite development server
3. Makes your app available at https://localhost:5173

Prerequisites:

• Install MagentrixCLI globally: npm install -g @magentrix-corp/magentrix-cli
• Ensure .env.development is properly configured with VITE_SITE_URL and VITE_REFRESH_TOKEN

Development

Building Your Application

Build your application by adding:

• Components in src/components/
• Views in src/views/
• Services for business logic
• Routes in your router configuration
• Styles using Tailwind CSS 4.1 utilities and Magentrix CSS variables

Using the Magentrix SDK

This template has a dependency on @magentrix-corp/magentrix-sdk, which provides the dataService for interacting with the Magentrix platform.

Initialize the SDK:

import { magentrixConfig } from '@/env-helper'
import { useMagentrixSdk } from '@magentrix-corp/magentrix-sdk/vue'

const dataService = useMagentrixSdk().getInstance(magentrixConfig)

Common dataService Methods:

// Query data with MEQL
const result = await dataService.query('SELECT Id, Name FROM Account LIMIT 10')

// Retrieve a single record
const result = await dataService.retrieve(recordId)

// Create a record
const result = await dataService.create({
  objectType: 'Contact',
  fields: { FirstName: 'John', LastName: 'Doe' }
})

// Update a record
await dataService.update({
  id: recordId,
  fields: { Name: 'Updated Name' }
})

// Delete a record
await dataService.delete(recordId)

// Get current user information
const userInfo = await dataService.getUserInfo()

// Call custom controller actions
const result = await dataService.execute(
  '/controller/action',
  { param: 'value' },
  RequestMethod.post
)

For complete API reference and detailed documentation, see the Magentrix SDK documentation.

User Interface Development

This template uses Tailwind CSS 4.1 for styling. For comprehensive guidance on building components that integrate with the Magentrix portal, see the AI Development Guide included in your project.

Key points:

• Use Tailwind utility classes for layout and spacing
• Use Magentrix CSS variables for colors and fonts to match the portal theme
• Combine both approaches for optimal results

Build for Production

Build your application and optionally publish to the Magentrix server using the Magentrix CLI command:

magentrix vue-run-build

This command:

1. Confirms the location of your Magentrix CLI project
2. Runs the build process to generate production files in the dist/ folder
3. Asks if you wish to publish the changes to the Magentrix server
4. Guides you through the publishing process if you choose to publish

Prerequisites:

• Install MagentrixCLI globally: npm install -g @magentrix-corp/magentrix-cli
• Have a Magentrix CLI project set up (required for publishing to the server)
• Ensure src/config.ts is properly configured with appSlug and appName

Deployment Path: Your app will be deployed to: <portal-url>/iris-app/{appSlug}/

Where {appSlug} is the value you configured in src/config.ts

Deployment

Deploy to Magentrix Server

The magentrix vue-run-build command handles the entire build and deployment process:

magentrix vue-run-build

What This Command Does:

1. Confirms the location of your Magentrix CLI project
2. Builds your application for production
3. Asks if you want to publish to the Magentrix server
4. Guides you through the publishing process

Requirements:

• MagentrixCLI: Install globally with npm install -g @magentrix-corp/magentrix-cli
• CLI Project: You must have a Magentrix CLI project set up locally
• Configuration: Ensure src/config.ts has appSlug and appName configured

Deployment Location: Your app will be accessible at: <portal-url>/iris-app/{appSlug}/

For more information about MagentrixCLI, visit: MagentrixCLI on npm

Project Structure

your-project/
├── src/
│   ├── assets/          # Static assets
│   ├── components/      # Vue components
│   ├── views/           # Page views
│   ├── config.ts        # Application configuration
│   ├── main.ts          # Standalone entry point
│   └── AppEntry.ts      # Module federation entry point
├── public/              # Public static files
├── package.json         # Project dependencies and scripts
├── vite.config.ts       # Vite and module federation configuration
└── tsconfig.json        # TypeScript configuration

Learn More

• Vue 3 Documentation
• TypeScript Guide
• Vite Documentation
• Vue Router
• Vue I18n

Support

For issues and questions, please refer to the Magentrix documentation at https://help.magentrix.com/ or contact support.

License

Proprietary