# Development Shell

This allows you to test your micro-frontend applications in a realistic setting with navigation, theming, and communication features.

### <mark style="color:red;">Usage</mark>

```bash
# Basic usage
pnpm shell

# With options
pnpm shell --config shell.config.js --port 4000
```

### <mark style="color:red;">Options</mark>

| Option            | Alias | Description                 | Default           |
| ----------------- | ----- | --------------------------- | ----------------- |
| `--config <path>` | `-c`  | Shell config file path      | `shell.config.js` |
| `--port <port>`   | `-p`  | Shell server port           | `4000`            |
| `--debug`         | `-d`  | Output extra debugging info | `false`           |

### <mark style="color:red;">Configuration</mark>

Create a `shell.config.js` file in your project root:

```javascript
export default {
  apps: [
    {
      url: 'http://localhost:5173',
      path: '/orders',
      name: 'Order Management',
      type: 'full_page',
      navTitle: 'Orders'
    },
    {
      url: 'http://localhost:5174',
      path: '/products',
      name: 'Product Catalog',
      type: 'full_page',
      navTitle: 'Products'
    },
    {
      url: 'http://localhost:5175',
      path: '/widgets/stats',
      name: 'Stats Widget',
      type: 'plugin'
    }
  ],
  shell: {
    port: 4000,
    theme: 'omnitron',
    title: 'My Development Shell'
  },
  sidebar: {
    items: [
      { key: 'orders', label: 'Orders', icon: 'shopping-cart' },
      { key: 'products', label: 'Products', icon: 'box' },
      {
        key: 'settings',
        label: 'Settings',
        icon: 'settings',
        children: [
          { key: 'general', label: 'General' },
          { key: 'users', label: 'Users' }
        ]
      }
    ]
  },
  data: {
    user: {
      id: 1,
      name: 'Dev User',
      email: 'dev@example.com',
      role: 'admin'
    },
    tenant: {
      id: 'demo-tenant',
      name: 'Demo Tenant'
    }
  }
};
```

### <mark style="color:red;">Configuration Reference</mark>

#### ShellConfig

```typescript
interface ShellConfig {
  apps: AppConfig[];
  shell: {
    port: number;
    theme: 'omnitron' | 'seller-center' | 'minimal';
    title: string;
  };
  sidebar?: {
    items: SidebarItem[];
  };
  data?: Record<string, unknown>;
}
```

#### AppConfig

```typescript
interface AppConfig {
  url: string;           // URL where the app is running
  path: string;          // Path in the shell where the app will be mounted
  name: string;          // Display name for the app
  type: 'full_page' | 'plugin';
  navTitle?: string;     // Navigation title (for full_page apps)
}
```

#### SidebarItem

```typescript
interface SidebarItem {
  key: string;           // Unique identifier
  label: string;         // Display label
  icon?: string;         // Icon name
  active?: boolean;      // Whether item is active
  children?: SidebarItem[];  // Nested items
}
```

### <mark style="color:red;">Themes</mark>

The development shell supports three themes:

#### omnitron

The default Akinon Omnitron theme with a dark sidebar and professional look.

```javascript
shell: {
  theme: 'omnitron'
}
```

#### seller-center

A lighter theme designed for seller-facing applications.

```javascript
shell: {
  theme: 'seller-center'
}
```

#### minimal

A minimal theme for testing without visual distractions.

```javascript
shell: {
  theme: 'minimal'
}
```

### <mark style="color:red;">Shared Data</mark>

Pass data to your applications via the `data` property:

```javascript
data: {
  user: {
    id: 1,
    name: 'Test User',
    email: 'test@example.com',
    role: 'admin'
  },
  tenant: {
    id: 'test-tenant',
    name: 'Test Tenant'
  },
  settings: {
    currency: 'USD',
    timezone: 'UTC'
  }
}
```

Access this data in your client application:

```tsx
const { data } = useAppClient();

console.log(data?.user?.name);  // 'Test User'
console.log(data?.tenant?.id);  // 'test-tenant'
```

### <mark style="color:red;">Development Workflow</mark>

#### Running Multiple Applications

Terminal 1 - Start your application:

```bash
cd my-app
pnpm dev  # Runs on http://localhost:5173
```

Terminal 2 - Start the shell:

```bash
cd my-app
pnpm shell  # Runs on http://localhost:4000
```

Open `http://localhost:4000` in your browser to see your application running inside the shell.

#### Testing Plugin Applications

Configure a plugin in your shell config:

```javascript
apps: [
  {
    url: 'http://localhost:5173',
    path: '/plugin-test',
    name: 'My Plugin',
    type: 'plugin'
  }
]
```

The shell provides a plugin testing area where you can:

* View the plugin in isolation
* Test with different parameters
* Switch locales
* Inspect communication events

#### Hot Module Replacement

Both the shell and your application support HMR. Changes to your code will be reflected immediately without losing application state.

### <mark style="color:red;">Common Issues</mark>

#### Port Already in Use

```bash
❌ Failed to start shell server:
   Port is already in use. Try a different port:
   akinon-ui shell --port 5001
```

Solution: Use a different port or kill the process using the current port.

#### Configuration Not Found

```bash
❌ Shell configuration not found at: /path/to/shell.config.js
```

Solution: Create a `shell.config.js` file or specify the correct path:

```bash
pnpm shell --config ./config/shell.config.js
```

#### CORS Issues

If you encounter CORS errors, ensure your application's Vite config allows the shell origin:

```typescript
// vite.config.ts
export default defineConfig({
  server: {
    cors: true
  }
});
```

### <mark style="color:red;">Example Configuration</mark>

#### Fullpage Application

```javascript
// shell.config.js
export default {
  apps: [
    {
      url: 'http://localhost:5173',
      path: '/my-app',
      name: 'My Application',
      type: 'full_page',
      navTitle: 'My App'
    }
  ],
  shell: {
    port: 4000,
    theme: 'omnitron',
    title: 'Development Shell'
  },
  sidebar: {
    items: [
      { key: 'my-app', label: 'My Application', icon: 'dashboard', active: true }
    ]
  },
  data: {
    user: { id: 1, name: 'Developer' }
  }
};
```

#### Multiple Applications

```javascript
// shell.config.js
export default {
  apps: [
    {
      url: 'http://localhost:5173',
      path: '/orders',
      name: 'Order Management',
      type: 'full_page',
      navTitle: 'Orders'
    },
    {
      url: 'http://localhost:5174',
      path: '/inventory',
      name: 'Inventory',
      type: 'full_page',
      navTitle: 'Inventory'
    }
  ],
  shell: {
    port: 4000,
    theme: 'seller-center',
    title: 'E-Commerce Admin'
  },
  sidebar: {
    items: [
      { key: 'orders', label: 'Orders', icon: 'shopping-cart' },
      { key: 'inventory', label: 'Inventory', icon: 'package' }
    ]
  }
};
```

### <mark style="color:red;">Next Steps</mark>

* Create Application - Create a new project
* Examples - See complete examples


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.akinon.com/akinon-ui/cli/commands/development-shell.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.