Development Shell

The shell command starts a development shell server that simulates the production shell environment.

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

Usage

# Basic usage
pnpm shell

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

Options

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

Configuration

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

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: '[email protected]',
      role: 'admin'
    },
    tenant: {
      id: 'demo-tenant',
      name: 'Demo Tenant'
    }
  }
};

Configuration Reference

ShellConfig

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

AppConfig

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

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

Themes

The development shell supports three themes:

omnitron

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

shell: {
  theme: 'omnitron'
}

seller-center

A lighter theme designed for seller-facing applications.

shell: {
  theme: 'seller-center'
}

minimal

A minimal theme for testing without visual distractions.

shell: {
  theme: 'minimal'
}

Shared Data

Pass data to your applications via the data property:

data: {
  user: {
    id: 1,
    name: 'Test User',
    email: '[email protected]',
    role: 'admin'
  },
  tenant: {
    id: 'test-tenant',
    name: 'Test Tenant'
  },
  settings: {
    currency: 'USD',
    timezone: 'UTC'
  }
}

Access this data in your client application:

const { data } = useAppClient();

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

Development Workflow

Running Multiple Applications

Terminal 1 - Start your application:

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

Terminal 2 - Start the shell:

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:

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.

Common Issues

Port Already in Use

❌ 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

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

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

pnpm shell --config ./config/shell.config.js

CORS Issues

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

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

Example Configuration

Fullpage Application

// 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

// 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' }
    ]
  }
};

Next Steps

• Create Application - Create a new project

• Examples - See complete examples