The development shell server is a powerful feature that simulates the Omnitron environment, allowing you to test your UI Protocol applications in a realistic context during development. Every project created with create-akinon-app includes this functionality out of the box.

What is the Shell Server?

The shell server provides a development environment that mirrors how your application will behave when integrated with main applications like Omnitron or Seller Center. It creates a complete application shell with:

• Navigation structure - Realistic menu and routing system
• Authentication context - User session simulation
• Theme integration - Proper styling and UI Kit integration
• Plugin loading - iframe-based micro application loading
• Data sharing - PostMessage API communication

Starting the Shell Server

Once your project is created, you can start the shell server with:

pnpm dev:shell

This command will:

1. Start the shell server on http://localhost:3000
2. Load your application within the shell environment
3. Provide hot reloading for both shell and application code

Shell Features

Theme Support

The shell server supports multiple themes to match different main applications:

• Omnitron - The default theme matching Omnitron’s appearance
• Seller Center - Theme for Seller Center integrations
• Minimal - A clean theme for focused development

Plugin Integration

For plugin applications, the shell server automatically:

• Loads your plugin in the appropriate placeholder
• Handles iframe communication
• Provides proper isolation and security
• Simulates real plugin loading behavior

Navigation and Routing

The shell includes a complete navigation system that:

• Displays your application in the correct context
• Handles routing between different sections
• Provides breadcrumbs and page titles
• Simulates the full user experience

Configuration

The shell server automatically detects your project type and configures itself appropriately. For plugin projects, it reads configuration from your application to determine:

• Plugin mounting location
• Required permissions
• Menu integration points
• Communication protocols

Development Workflow

Typical Development Process

1. Start both servers:

   # Terminal 1: Start your application
   pnpm dev
    
   # Terminal 2: Start the shell
   pnpm dev:shell

2. Develop with hot reloading:

   • Edit your application code
   • See changes instantly in the shell environment
   • Test integration features in real-time

3. Test different scenarios:

   • Navigate through different shell sections
   • Test data sharing and communication
   • Verify theme compatibility

Testing Integration Features

The shell server is perfect for testing:

• Data Exchange - How your app communicates with the shell
• Navigation - How users will navigate to and within your app
• Permissions - How your app behaves with different user roles
• Responsive Design - How your app adapts to different container sizes
• Error Handling - How your app handles integration failures

Shell vs Direct Development

Using Shell Development

• Pros: Realistic testing environment, integration testing, theme verification
• Cons: Slightly slower startup, more complex debugging
• Best for: Plugin apps, integration testing, final verification

Using Direct Development

• Pros: Faster startup, simpler debugging, focused development
• Cons: No integration context, theme differences
• Best for: Component development, rapid prototyping, unit testing

Advanced Configuration

Custom Shell Configuration

For advanced use cases, you can customize the shell behavior by creating a shell.config.js file in your project root:

export default {
  shell: {
    port: 3000,
    theme: 'omnitron',
    title: 'My App Development'
  },
  plugin: {
    url: 'http://localhost:3002',
    path: './src',
    name: 'My Plugin'
  }
};

Environment Variables

Control shell behavior with environment variables:

# Change shell theme
SHELL_THEME=seller-center pnpm dev:shell
 
# Custom shell port
SHELL_PORT=3001 pnpm dev:shell
 
# Debug mode
SHELL_DEBUG=true pnpm dev:shell

Troubleshooting

Common Issues

Shell won’t start:

• Check if port 3000 is available
• Ensure dependencies are installed
• Verify your project was created with recent CLI version

Plugin not loading:

• Confirm your main app is running on the expected port
• Check browser console for iframe loading errors
• Verify your app’s CORS configuration

Theme issues:

• Ensure UI Kit is properly imported
• Check for CSS conflicts
• Verify theme configuration matches expected environment

Getting Help

If you encounter issues with the shell server:

1. Check the console output for error messages
2. Verify your project structure matches the expected template
3. Ensure all dependencies are up to date
4. Test with a fresh project to isolate configuration issues

The shell development server significantly improves the development experience by providing immediate feedback on how your application will behave in production environments.