create-lego-one 2.0.10 → 2.0.13

package/template/docs/framework/research/03-host-setup.md

@@ -0,0 +1,714 @@
+# Host Setup: Modern.js with Tailwind + Shadcn
+
+**Project:** Lego-One (Modern.js SaaS OS)
+**Document:** 03 - Host Setup Guide
+**Status:** Research Phase
+
+## Executive Summary
+
+Step-by-step guide to initialize the Modern.js Host (Kernel) application with Tailwind CSS and Shadcn UI. Since Shadcn is optimized for Next.js, we need specific configuration for Modern.js compatibility.
+
+---
+
+## 1. Project Initialization
+
+### 1.1 Create Host Project
+
+```bash
+# Create the host directory
+mkdir lego-one
+cd lego-one
+
+# Initialize Modern.js project
+npx @modern-js/create@latest host
+
+# Select options:
+# - Language: TypeScript
+# - Package manager: pnpm
+# - Git: Yes
+```
+
+```bash
+cd host
+
+# Enable Micro Frontend feature
+pnpm run new
+# Select: Enable features -> Micro Front-end Feature
+```
+
+### 1.2 Install Core Dependencies
+
+```bash
+cd host
+
+# UI System
+pnpm add tailwindcss postcss autoprefixer
+pnpm add @radix-ui/react-slot
+pnpm add class-variance-authority clsx tailwind-merge
+
+# State Management
+pnpm add zustand
+
+# Server State
+pnpm add @tanstack/react-query
+
+# Notifications
+pnpm add sonner
+
+# Backend
+pnpm add pocketbase
+
+# Icons
+pnpm add lucide-react
+
+# Additional Radix Primitives (for Shadcn)
+pnpm add @radix-ui/react-dialog
+pnpm add @radix-ui/react-dropdown-menu
+pnpm add @radix-ui/react-label
+pnpm add @radix-ui/react-select
+pnpm add @radix-ui/react-separator
+pnpm add @radix-ui/react-switch
+pnpm add @radix-ui/react-tabs
+pnpm add @radix-ui/react-toast
+```
+
+### 1.3 Install Dev Dependencies
+
+```bash
+# Type safety
+pnpm add -D @types/node
+
+# Shadcn CLI
+pnpm add -D shadcn-ui
+```
+
+---
+
+## 2. Tailwind CSS Configuration
+
+### 2.1 Initialize Tailwind
+
+```bash
+# This will create tailwind.config.js and postcss.config.js
+npx tailwindcss init -p
+```
+
+### 2.2 Configure Tailwind for Modern.js
+
+**File:** `host/tailwind.config.js`
+
+```javascript
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  darkMode: ['class'],
+  content: [
+    './src/**/*.{ts,tsx}',
+    // Include Shadcn components when we add them
+    './src/components/**/*.{ts,tsx}',
+  ],
+  theme: {
+    container: {
+      center: true,
+      padding: '2rem',
+      screens: {
+        '2xl': '1400px',
+      },
+    },
+    extend: {
+      colors: {
+        border: 'hsl(var(--border))',
+        input: 'hsl(var(--input))',
+        ring: 'hsl(var(--ring))',
+        background: 'hsl(var(--background))',
+        foreground: 'hsl(var(--foreground))',
+        primary: {
+          DEFAULT: 'hsl(var(--primary))',
+          foreground: 'hsl(var(--primary-foreground))',
+        },
+        secondary: {
+          DEFAULT: 'hsl(var(--secondary))',
+          foreground: 'hsl(var(--secondary-foreground))',
+        },
+        destructive: {
+          DEFAULT: 'hsl(var(--destructive))',
+          foreground: 'hsl(var(--destructive-foreground))',
+        },
+        muted: {
+          DEFAULT: 'hsl(var(--muted))',
+          foreground: 'hsl(var(--muted-foreground))',
+        },
+        accent: {
+          DEFAULT: 'hsl(var(--accent))',
+          foreground: 'hsl(var(--accent-foreground))',
+        },
+        popover: {
+          DEFAULT: 'hsl(var(--popover))',
+          foreground: 'hsl(var(--popover-foreground))',
+        },
+        card: {
+          DEFAULT: 'hsl(var(--card))',
+          foreground: 'hsl(var(--card-foreground))',
+        },
+      },
+      borderRadius: {
+        lg: 'var(--radius)',
+        md: 'calc(var(--radius) - 2px)',
+        sm: 'calc(var(--radius) - 4px)',
+      },
+      keyframes: {
+        'accordion-down': {
+          from: { height: '0' },
+          to: { height: 'var(--radix-accordion-content-height)' },
+        },
+        'accordion-up': {
+          from: { height: 'var(--radix-accordion-content-height)' },
+          to: { height: '0' },
+        },
+      },
+      animation: {
+        'accordion-down': 'accordion-down 0.2s ease-out',
+        'accordion-up': 'accordion-up 0.2s ease-out',
+      },
+    },
+  },
+  plugins: [require('tailwindcss-animate')],
+};
+```
+
+### 2.3 Install Tailwind Animate Plugin
+
+```bash
+pnpm add -D tailwindcss-animate
+```
+
+### 2.4 Configure PostCSS
+
+**File:** `host/postcss.config.js`
+
+```javascript
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
+```
+
+**NOTE:** Modern.js has built-in PostCSS support. The above config works alongside Modern.js's default PostCSS configuration.
+
+### 2.5 Verify Modern.js PostCSS Integration
+
+**File:** `host/modern.config.ts`
+
+```typescript
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { garfishPlugin } from '@modern-js/plugin-garfish';
+
+export default defineConfig({
+  // Modern.js handles PostCSS automatically
+  // No extra config needed for Tailwind to work
+  tools: {
+    postcss: (config, { addPlugins }) => {
+      // Optionally add custom PostCSS plugins
+      // addPlugins([...]);
+      return config;
+    },
+  },
+
+  runtime: {
+    router: true,
+  },
+
+  plugins: [appTools(), garfishPlugin()],
+});
+```
+
+---
+
+## 3. Global Styles
+
+### 3.1 Create CSS Variables
+
+**File:** `host/src/styles/globals.css`
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 222.2 84% 4.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 222.2 84% 4.9%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 222.2 84% 4.9%;
+    --primary: 222.2 47.4% 11.2%;
+    --primary-foreground: 210 40% 98%;
+    --secondary: 210 40% 96.1%;
+    --secondary-foreground: 222.2 47.4% 11.2%;
+    --muted: 210 40% 96.1%;
+    --muted-foreground: 215.4 16.3% 46.9%;
+    --accent: 210 40% 96.1%;
+    --accent-foreground: 222.2 47.4% 11.2%;
+    --destructive: 0 84.2% 60.2%;
+    --destructive-foreground: 210 40% 98%;
+    --border: 214.3 31.8% 91.4%;
+    --input: 214.3 31.8% 91.4%;
+    --ring: 222.2 84% 4.9%;
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 222.2 84% 4.9%;
+    --foreground: 210 40% 98%;
+    --card: 222.2 84% 4.9%;
+    --card-foreground: 210 40% 98%;
+    --popover: 222.2 84% 4.9%;
+    --popover-foreground: 210 40% 98%;
+    --primary: 210 40% 98%;
+    --primary-foreground: 222.2 47.4% 11.2%;
+    --secondary: 217.2 32.6% 17.5%;
+    --secondary-foreground: 210 40% 98%;
+    --muted: 217.2 32.6% 17.5%;
+    --muted-foreground: 215 20.2% 65.1%;
+    --accent: 217.2 32.6% 17.5%;
+    --accent-foreground: 210 40% 98%;
+    --destructive: 0 62.8% 30.6%;
+    --destructive-foreground: 210 40% 98%;
+    --border: 217.2 32.6% 17.5%;
+    --input: 217.2 32.6% 17.5%;
+    --ring: 212.7 26.8% 83.9%;
+  }
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+```
+
+### 3.2 Import Global Styles
+
+**File:** `host/src/main.tsx` (or update existing entry point)
+
+```typescript
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+import './styles/globals.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);
+```
+
+---
+
+## 4. Shadcn UI Setup for Modern.js
+
+### 4.1 Initialize Shadcn
+
+Since Shadcn uses Next.js-specific features, we need to configure it manually for Modern.js.
+
+**File:** `host/components.json`
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "default",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.js",
+    "css": "src/styles/globals.css",
+    "baseColor": "slate",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  }
+}
+```
+
+### 4.2 Create Path Aliases
+
+**File:** `host/tsconfig.json`
+
+```json
+{
+  "extends": "@modern-js/tsconfig/base",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"]
+}
+```
+
+### 4.3 Update Modern.js Config for Path Aliases
+
+**File:** `host/modern.config.ts`
+
+```typescript
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { garfishPlugin } from '@modern-js/plugin-garfish';
+
+export default defineConfig({
+  source: {
+    alias: {
+      '@': './src',
+    },
+  },
+
+  runtime: {
+    router: true,
+  },
+
+  plugins: [appTools(), garfishPlugin()],
+});
+```
+
+### 4.4 Create Utility Functions
+
+**File:** `host/src/lib/utils.ts`
+
+```typescript
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+```
+
+### 4.5 Add Shadcn Components
+
+Use Shadcn CLI to add components:
+
+```bash
+# Example: Add button component
+npx shadcn-ui@latest add button
+```
+
+**NOTE:** You may need to manually move components to the correct location after CLI adds them, as Shadcn expects Next.js structure.
+
+**Manual Alternative:** Copy component code from [shadcn/ui](https://ui.shadcn.com/) to `host/src/components/ui/`
+
+**Example:** `host/src/components/ui/button.tsx`
+
+```typescript
+import * as React from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '@/lib/utils';
+
+const buttonVariants = cva(
+  'inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        destructive:
+          'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+        outline:
+          'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
+        secondary:
+          'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        ghost: 'hover:bg-accent hover:text-accent-foreground',
+        link: 'text-primary underline-offset-4 hover:underline',
+      },
+      size: {
+        default: 'h-10 px-4 py-2',
+        sm: 'h-9 rounded-md px-3',
+        lg: 'h-11 rounded-md px-8',
+        icon: 'h-10 w-10',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+    },
+  }
+);
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean;
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : 'button';
+    return (
+      <Comp
+        className={cn(buttonVariants({ variant, size, className }))}
+        ref={ref}
+        {...props}
+      />
+    );
+  }
+);
+Button.displayName = 'Button';
+
+export { Button, buttonVariants };
+```
+
+---
+
+## 5. Garfish Micro-Frontend Configuration
+
+### 5.1 Configure Garfish Plugin
+
+**File:** `host/modern.config.ts`
+
+```typescript
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { garfishPlugin } from '@modern-js/plugin-garfish';
+
+export default defineConfig({
+  runtime: {
+    router: true,
+  },
+
+  plugins: [appTools(), garfishPlugin()],
+
+  // Rspack configuration for optimal performance
+  tools: {
+    rspack: (config, { addRules }) => {
+      return config;
+    },
+  },
+});
+```
+
+### 5.2 Configure Sub-Apps
+
+**File:** `host/src/modern.runtime.ts`
+
+```typescript
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig({
+  masterApp: {
+    apps: [
+      {
+        name: '@lego/plugin-dashboard',
+        entry: 'http://localhost:3001',
+        activeWhen: '/dashboard',
+      },
+      {
+        name: '@lego/plugin-loan-calculator',
+        entry: 'http://localhost:3002',
+        activeWhen: '/apps/loan',
+      },
+    ],
+  },
+});
+```
+
+---
+
+## 6. Shared State Bridge Setup
+
+### 6.1 Create Zustand Store
+
+**File:** `host/src/kernel/shared-state-bridge.ts`
+
+```typescript
+import { create } from 'zustand';
+import { devtools, persist } from 'zustand/middleware';
+
+interface GlobalKernelState {
+  // User
+  currentUser: {
+    id: string;
+    email: string;
+    role: string;
+  } | null;
+
+  // UI State
+  theme: 'light' | 'dark';
+  sidebarOpen: boolean;
+
+  // Actions
+  setCurrentUser: (user: GlobalKernelState['currentUser']) => void;
+  setTheme: (theme: 'light' | 'dark') => void;
+  toggleSidebar: () => void;
+}
+
+export const useGlobalKernelState = create<GlobalKernelState>()(
+  devtools(
+    persist(
+      (set) => ({
+        currentUser: null,
+        theme: 'light',
+        sidebarOpen: true,
+
+        setCurrentUser: (user) => set({ currentUser: user }),
+        setTheme: (theme) => set({ theme }),
+        toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
+      }),
+      {
+        name: 'lego-kernel-state',
+        partialize: (state) => ({ theme: state.theme, sidebarOpen: state.sidebarOpen }),
+      }
+    ),
+    { name: 'LegoKernelState' }
+  )
+);
+
+// Register to window for plugin access
+export function registerSharedState() {
+  (window as any).__LEGO_KERNEL_STATE__ = {
+    useGlobalKernelState,
+  };
+}
+```
+
+### 6.2 Initialize in Bootstrap
+
+**File:** `host/src/bootstrap.tsx`
+
+```typescript
+import { registerSharedState } from './kernel/shared-state-bridge';
+import './styles/globals.css';
+
+// Initialize shared state bridge before app starts
+registerSharedState();
+
+export {};
+```
+
+---
+
+## 7. Basic Layout Structure
+
+### 7.1 Create Main Layout
+
+**File:** `host/src/layout/AppLayout.tsx`
+
+```typescript
+import { Outlet } from '@modern-js/runtime/router';
+import { Sidebar } from './Sidebar';
+import { Topbar } from './Topbar';
+import { Toaster } from '@/components/ui/sonner';
+
+export function AppLayout() {
+  return (
+    <div className="flex h-screen bg-background">
+      <Sidebar />
+      <div className="flex flex-col flex-1 overflow-hidden">
+        <Topbar />
+        <main className="flex-1 overflow-auto p-6">
+          <Outlet />
+        </main>
+      </div>
+      <Toaster />
+    </div>
+  );
+}
+```
+
+### 7.2 Create Root Layout
+
+**File:** `host/src/routes/layout.tsx`
+
+```typescript
+import { Outlet } from '@modern-js/runtime/router';
+import { AppLayout } from '@/layout/AppLayout';
+
+export default function Layout() {
+  return (
+    <AppLayout>
+      <Outlet />
+    </AppLayout>
+  );
+}
+```
+
+---
+
+## 8. Verification Steps
+
+### 8.1 Test Tailwind
+
+**File:** `host/src/routes/page.tsx`
+
+```typescript
+export default function Home() {
+  return (
+    <div className="p-8">
+      <h1 className="text-4xl font-bold text-primary">Lego-One Host</h1>
+      <p className="text-muted-foreground mt-4">
+        Modern.js + Tailwind + Shadcn
+      </p>
+    </div>
+  );
+}
+```
+
+### 8.2 Test Shadcn Component
+
+```typescript
+import { Button } from '@/components/ui/button';
+
+export default function Home() {
+  return (
+    <div className="p-8">
+      <Button>Click Me</Button>
+    </div>
+  );
+}
+```
+
+### 8.3 Run Development Server
+
+```bash
+pnpm run dev
+# Navigate to http://localhost:8080
+```
+
+---
+
+## 9. Key Differences from Next.js
+
+| Feature | Next.js | Modern.js | Solution |
+|---------|---------|-----------|----------|
+| Routing | App Router | File-based (routes/) | Use `routes/` directory |
+| Imports | `@/` alias | Needs config | Set `source.alias` in modern.config.ts |
+| CSS | Global CSS auto-imported | Manual import | Import in `main.tsx` |
+| PostCSS | Built-in config | Built-in config | Works the same |
+| RSC | Supported | Not supported | Use client components |
+
+---
+
+## 10. Next Steps
+
+1. **`04-plugin-architecture.md`**: Create a "Hello World" plugin
+2. **`05-slot-injection-pattern.md`**: Implement UI slot system
+3. **`06-cli-strategy.md`**: CLI tool for project scaffolding
+
+---
+
+## References
+
+- [Modern.js Tailwind CSS Guide](https://modernjs.dev/guides/basic-features/css/tailwindcss)
+- [Shadcn UI Documentation](https://ui.shadcn.com/)
+- [Rsbuild Tailwind CSS v3 Guide](https://rsbuild.rs/guide/styling/tailwindcss-v3)
+- [Modern.js Micro Frontend Guide](https://modernjs.dev/guides/topic-detail/micro-frontend/c02-development)