feat: add support for multiple runtime modes (MSW and Server) in the console application

Author: hotlong

apps/console/.env.example

@@ -0,0 +1,11 @@
+# Environment Variables
+# Copy this file to .env.local and customize
+
+# Runtime Mode
+# Options: 'msw' (default) | 'server'
+# - msw: Use Mock Service Worker with in-browser ObjectStack kernel
+# - server: Connect to a real ObjectStack server
+VITE_RUNTIME_MODE=msw
+
+# ObjectStack Server URL (used when VITE_RUNTIME_MODE=server)
+# VITE_SERVER_URL=http://localhost:5000/api/v1

apps/console/README.md

@@ -14,7 +14,11 @@ ObjectStack Console provides a modern, responsive admin interface that:
 
 ## 🏗️ Architecture
 
-The console runs the ObjectStack Runtime directly in the browser using MSW (Mock Service Worker), enabling full offline development.
+The console supports two runtime modes:
+
+### MSW Mode (Default)
+
+Runs the ObjectStack Runtime directly in the browser using MSW (Mock Service Worker), enabling full offline development.
 
 ```mermaid
 graph TD
@@ -25,18 +29,41 @@ graph TD
     Kernel -.->|Reads| Config["objectstack.config.ts"]
 ```
 
+### Server Mode
+
+Connects to a real ObjectStack server for production use or integration testing.
+
+```mermaid
+graph TD
+    Console["Console App"] -->|REST API| Server["ObjectStack Server"]
+    Server -->|Processes| Kernel["ObjectStack Kernel"]
+    Kernel -->|Uses| Driver["Database Driver"]
+```
+
 ## 🚀 Quick Start
 
 ```bash
 # Install dependencies
 pnpm install
 
-# Start development server
+# Start development server (MSW mode)
 pnpm dev
+
+# Start in server mode (connects to real backend)
+VITE_RUNTIME_MODE=server VITE_SERVER_URL=http://localhost:5000/api/v1 pnpm dev
 ```
 
 The console will be available at `http://localhost:3000`.
 
+## ⚙️ Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VITE_RUNTIME_MODE` | `msw` | Runtime mode: `msw` or `server` |
+| `VITE_SERVER_URL` | `http://localhost:5000/api/v1` | Server URL (server mode only) |
+
+Copy `.env.example` to `.env.local` to customize:
+
 ## 📁 Project Structure
 
 ```

apps/console/src/App.tsx

@@ -8,6 +8,7 @@ import { ObjectDataForm } from './components/ObjectDataForm';
 import { Toaster } from "@/components/ui/toaster"
 import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card"
 import { Database, Layers, Sparkles, Zap } from 'lucide-react';
+import { getApiBaseUrl, config } from './lib/config';
 
 function DashboardWelcome() {
   return (
@@ -122,7 +123,10 @@ export default function App() {
   const [showForm, setShowForm] = useState(false);
 
   useEffect(() => {
-    const baseUrl = '/api/v1'; 
+    // Use the configured API base URL based on runtime mode (MSW or Server)
+    const baseUrl = getApiBaseUrl();
+    console.log(`[App] Connecting to API: ${baseUrl} (mode: ${config.mode})`);
+    
     const newClient = new ObjectStackClient({
       baseUrl,
     });

apps/console/src/lib/config.ts

@@ -0,0 +1,103 @@
+/**
+ * Console Application Configuration
+ * 
+ * Supports two runtime modes:
+ * - MSW Mode: Uses Mock Service Worker with in-browser ObjectStack kernel
+ * - Server Mode: Connects to a real ObjectStack server
+ */
+
+export type RuntimeMode = 'msw' | 'server';
+
+export interface ConsoleConfig {
+  /**
+   * Runtime mode
+   * - 'msw': Mock Service Worker mode (browser-based kernel)
+   * - 'server': Connect to real ObjectStack server
+   */
+  mode: RuntimeMode;
+  
+  /**
+   * Server base URL (used in 'server' mode)
+   * @default 'http://localhost:5000/api/v1'
+   */
+  serverUrl: string;
+  
+  /**
+   * MSW API base path (used in 'msw' mode)
+   * @default '/api/v1'
+   */
+  mswBasePath: string;
+}
+
+/**
+ * Get runtime mode from environment
+ */
+function getRuntimeMode(): RuntimeMode {
+  const envMode = import.meta.env.VITE_RUNTIME_MODE;
+  
+  if (envMode === 'server') {
+    return 'server';
+  }
+  
+  // Default to MSW mode for development
+  return 'msw';
+}
+
+/**
+ * Default configuration values
+ */
+const defaultConfig: ConsoleConfig = {
+  mode: getRuntimeMode(),
+  serverUrl: import.meta.env.VITE_SERVER_URL || 'http://localhost:5000/api/v1',
+  mswBasePath: '/api/v1',
+};
+
+/**
+ * Current application configuration
+ */
+export const config: ConsoleConfig = {
+  ...defaultConfig,
+};
+
+/**
+ * Check if running in MSW mode
+ */
+export function isMswMode(): boolean {
+  return config.mode === 'msw';
+}
+
+/**
+ * Check if running in Server mode
+ */
+export function isServerMode(): boolean {
+  return config.mode === 'server';
+}
+
+/**
+ * Get the API base URL based on current mode
+ */
+export function getApiBaseUrl(): string {
+  if (isServerMode()) {
+    return config.serverUrl;
+  }
+  return config.mswBasePath;
+}
+
+/**
+ * Update configuration at runtime
+ * Useful for switching modes programmatically
+ */
+export function updateConfig(updates: Partial<ConsoleConfig>): void {
+  Object.assign(config, updates);
+}
+
+/**
+ * Log current configuration (for debugging)
+ */
+export function logConfig(): void {
+  console.log('[Console Config]', {
+    mode: config.mode,
+    apiBaseUrl: getApiBaseUrl(),
+    serverUrl: config.serverUrl,
+  });
+}

apps/console/src/main.tsx

@@ -1,7 +1,12 @@
 /**
  * Main Entry Point
  * 
- * Initializes MSW and renders the React application.
+ * Initializes the console application with support for two runtime modes:
+ * - MSW Mode: Uses Mock Service Worker with in-browser ObjectStack kernel
+ * - Server Mode: Connects to a real ObjectStack server
+ * 
+ * Set VITE_RUNTIME_MODE=server to connect to a real server
+ * Set VITE_RUNTIME_MODE=msw (or leave empty) for MSW mode
  */
 
 import './mocks/process-polyfill';
@@ -11,11 +16,20 @@ import './index.css';
 import App from './App';
 import { AppWithHooks } from './AppWithHooks';
 import { startMockServer } from './mocks/browser';
+import { config, isMswMode, logConfig } from './lib/config';
 
-// Start MSW before rendering the app
+// Bootstrap the application
 async function bootstrap() {
-  // Initialize Mock Service Worker
-  await startMockServer();
+  // Log current configuration
+  logConfig();
+
+  // Only start MSW in MSW mode
+  if (isMswMode()) {
+    console.log('[Console] Starting in MSW mode (in-browser kernel)');
+    await startMockServer();
+  } else {
+    console.log(`[Console] Starting in Server mode (connecting to ${config.serverUrl})`);
+  }
 
   // Switch between traditional approach and hooks-based approach
   // Change this to true to use the hooks version

apps/console/src/vite-env.d.ts

@@ -0,0 +1,19 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  /**
+   * Runtime mode for the console application
+   * - 'msw': Mock Service Worker mode (browser-based kernel)
+   * - 'server': Connect to real ObjectStack server
+   */
+  readonly VITE_RUNTIME_MODE: 'msw' | 'server';
+  
+  /**
+   * ObjectStack server URL (used when VITE_RUNTIME_MODE=server)
+   */
+  readonly VITE_SERVER_URL: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}