npm package: @magentrix-corp/create-iris-app-template
Description: Magentrix starter template for Iris apps.
Latest version: 1.1.17

# 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:

```bash
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:

```bash
cd your-project-name
```

Open `.env.development` and update it with your Magentrix portal credentials:

```env
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:

```typescript
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:

```bash
npm install
```

### Step 4: Start Development

Start the local development server using the Magentrix CLI command:

```bash
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](https://www.npmjs.com/package/@magentrix-corp/magentrix-sdk)**, which provides the `dataService` for interacting with the Magentrix platform.

**Initialize the SDK:**
```typescript
import { magentrixConfig } from '@/env-helper'
import { useMagentrixSdk } from '@magentrix-corp/magentrix-sdk/vue'

const dataService = useMagentrixSdk().getInstance(magentrixConfig)
```

**Common dataService Methods:**

```typescript
// 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
)
```

**App Security:**

By default, app security is enforced based on the corresponding menu item security permissions set in the Magentrix back-end using the Navigation Menu setup. The router is created via the `createAppRouter(basePath)` factory function in `src/router/index.ts`, which includes a `beforeEach` guard that checks access automatically.

The default implementation looks like this:

```typescript
router.beforeEach(async (to, from) => {
    const sdk = useMagentrixSdk().getInstance(magentrixConfig)
    const appAccessInfo = await sdk.getIrisAppAccessInfo(config.appSlug)
    const hasAccess = appAccessInfo.hasAccess ?? false

    if (!hasAccess)
      sdk.forwardToUnauthorizedPath(appAccessInfo)

    return hasAccess
})
```

This guard calls `getIrisAppAccessInfo()` to check the user's access, and if denied, delegates to `forwardToUnauthorizedPath()` which redirects the user to the appropriate unauthorized page.

**Disabling the permission check for performance:**

`getIrisAppAccessInfo` accepts an optional second parameter `checkAppAccess` (boolean, defaults to `true`). When set to `false`, the API skips the permission check, which can improve performance for apps that don't need menu item security:

```typescript
const appAccessInfo = await sdk.getIrisAppAccessInfo(config.appSlug, false)
```

**To disable app security entirely:**

To bypass security and make the app accessible to everyone, remove the access check logic from the `beforeEach` guard inside `createAppRouter()` in `src/router/index.ts`:

```typescript
router.beforeEach(async (to, from) => {
    return true
})
```

**To customize security for certain routes:**

If your app has multiple pages with routing, you can allow or deny access to specific routes by checking the destination route name (`to.name`). Return `true` to allow access, or `false` to deny it. The following example prevents access to a route called `page2`, but all other routes remain accessible:

```typescript
router.beforeEach(async (to, from) => {
    if (to.name === 'page2')
      return false

    return true
})
```

**For complete API reference and detailed documentation**, see the [Magentrix SDK documentation](https://www.npmjs.com/package/@magentrix-corp/magentrix-sdk).

### 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:

```bash
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:

```bash
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](https://www.npmjs.com/package/@magentrix-corp/magentrix-cli)

## 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](https://vuejs.org/)
- [TypeScript Guide](https://vuejs.org/guide/typescript/overview.html)
- [Vite Documentation](https://vitejs.dev/)
- [Vue Router](https://router.vuejs.org/)
- [Vue I18n](https://vue-i18n.intlify.dev/)

## Support

For issues and questions, please refer to the Magentrix documentation at https://help.magentrix.com/ or contact support.

## License

Proprietary