@majkapp/plugin-kit 3.2.1 → 3.3.0

package/docs/CONFIG.md

@@ -0,0 +1,428 @@
+# Configuration
+
+Set up your plugin project with the correct structure and build configuration.
+
+## vite.config.js (REQUIRED FORMAT)
+
+**CRITICAL:** Use this EXACT format for your vite.config.js:
+
+```javascript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  root: 'ui',                    // React source is in ui/ directory
+  base: '',                      // IMPORTANT: Empty string, NOT './'
+  server: {
+    port: 3000,
+    strictPort: false,
+  },
+  build: {
+    outDir: '../dist',           // Build output to dist/ (parent of ui/)
+    assetsDir: 'assets',
+    emptyOutDir: true,
+  },
+});
+```
+
+**Why `base: ''`?**
+- MAJK loads plugins in iframes with dynamic paths
+- Empty base ensures assets load correctly
+- `base: './'` will cause 404 errors for assets
+
+## Project Structure
+
+```
+my-plugin/
+├── src/
+│   ├── index.ts              # Plugin definition (definePlugin)
+│   └── core/                 # Business logic (no plugin dependencies)
+│       ├── analytics.ts
+│       └── formatters.ts
+├── ui/
+│   ├── index.html
+│   ├── src/
+│   │   ├── main.tsx          # React entry point
+│   │   ├── App.tsx           # Router setup
+│   │   ├── components/
+│   │   │   ├── DashboardPage.tsx
+│   │   │   ├── SettingsPage.tsx
+│   │   │   └── shared/
+│   │   │       └── ErrorBoundary.tsx
+│   │   └── generated/        # Auto-generated (DO NOT EDIT)
+│   │       ├── hooks.ts      # useHealth(), useGetAnalytics(), etc.
+│   │       ├── client.ts     # RPC client
+│   │       ├── types.ts      # TypeScript types
+│   │       └── index.ts
+│   └── vite.config.js
+├── tests/
+│   └── plugin/
+│       ├── functions/
+│       │   └── unit/
+│       │       ├── health.test.js
+│       │       └── analytics.test.js
+│       └── ui/
+│           └── unit/
+│               ├── dashboard.test.js
+│               └── events-list.test.js
+├── dist/                     # Build output (ignored by git)
+│   ├── index.html
+│   ├── assets/
+│   │   ├── index-abc123.js
+│   │   └── index-def456.css
+│   └── index.js              # Plugin definition (compiled)
+├── package.json
+├── tsconfig.json
+├── .gitignore
+└── README.md
+```
+
+## package.json
+
+```json
+{
+  "name": "@yourorg/my-plugin",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "type": "commonjs",
+  "scripts": {
+    "build": "tsc && cd ui && npm run build",
+    "build:plugin": "tsc",
+    "build:ui": "cd ui && npm run build",
+    "dev": "cd ui && npm run dev",
+    "test:plugin:functions": "majk-test 'tests/plugin/functions/**/*.test.js'",
+    "test:plugin:ui": "majk-test 'tests/plugin/ui/**/*.test.js'",
+    "test:plugin": "majk-test 'tests/plugin/**/*.test.js'"
+  },
+  "dependencies": {
+    "@majkapp/plugin-kit": "^3.2.1"
+  },
+  "devDependencies": {
+    "@majkapp/plugin-test": "^1.0.0",
+    "@majkapp/plugin-ui": "^1.0.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-router-dom": "^6.11.0",
+    "typescript": "^5.0.0",
+    "vite": "^4.3.0"
+  }
+}
+```
+
+## tsconfig.json (Plugin)
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "ui", "tests"]
+}
+```
+
+## tsconfig.json (UI)
+
+```json
+// ui/tsconfig.json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}
+```
+
+## ui/index.html
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>My Plugin</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+## ui/src/main.tsx
+
+```typescript
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { App } from './App';
+import './index.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);
+```
+
+## ui/src/App.tsx
+
+```typescript
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import { DashboardPage } from './components/DashboardPage';
+import { SettingsPage } from './components/SettingsPage';
+
+export function App() {
+  // CRITICAL: Use window.__MAJK_IFRAME_BASE__ for basename
+  const basename = (window as any).__MAJK_IFRAME_BASE__ || '/';
+
+  return (
+    <BrowserRouter basename={basename}>
+      <Routes>
+        <Route path="/" element={<DashboardPage />} />
+        <Route path="/settings" element={<SettingsPage />} />
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+
+## .gitignore
+
+```
+# Dependencies
+node_modules/
+ui/node_modules/
+
+# Build output
+dist/
+ui/dist/
+
+# Test output
+tests/__screenshots__/
+
+# Logs
+*.log
+npm-debug.log*
+
+# Environment
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+```
+
+## Build Process
+
+### 1. Install Dependencies
+
+```bash
+# Root dependencies
+npm install
+
+# UI dependencies
+cd ui && npm install && cd ..
+```
+
+### 2. Build Plugin
+
+```bash
+npm run build
+```
+
+This runs:
+1. `tsc` - Compiles `src/index.ts` → `dist/index.js`
+2. `cd ui && npm run build` - Builds React app → `dist/` (assets)
+
+### 3. Generated Files
+
+After build, your `dist/` should contain:
+
+```
+dist/
+├── index.js              # Compiled plugin definition
+├── index.d.ts            # TypeScript declarations
+├── index.html            # Built React app
+└── assets/
+    ├── index-abc123.js   # Bundled React app
+    └── index-def456.css  # Bundled CSS
+```
+
+## Development Workflow
+
+### 1. Start UI Development Server
+
+```bash
+npm run dev
+```
+
+Opens UI at `http://localhost:3000` with hot reload.
+
+### 2. Build Plugin for Testing
+
+```bash
+npm run build:plugin
+```
+
+Compiles plugin without rebuilding UI.
+
+### 3. Full Build
+
+```bash
+npm run build
+```
+
+Compiles plugin AND builds UI for production.
+
+### 4. Run Tests
+
+```bash
+# All tests
+npm run test:plugin
+
+# Function tests only
+npm run test:plugin:functions
+
+# UI tests only
+npm run test:plugin:ui
+```
+
+## Environment Variables
+
+React app can access these globals:
+
+```typescript
+// ui/src/types/window.d.ts
+declare global {
+  interface Window {
+    __MAJK_BASE_URL__: string;      // Host base URL
+    __MAJK_IFRAME_BASE__: string;   // Plugin iframe base
+    __MAJK_PLUGIN_ID__: string;     // Your plugin ID
+  }
+}
+
+export {};
+```
+
+Usage:
+
+```typescript
+// ui/src/config.ts
+export const config = {
+  baseUrl: window.__MAJK_BASE_URL__,
+  iframeBase: window.__MAJK_IFRAME_BASE__,
+  pluginId: window.__MAJK_PLUGIN_ID__
+};
+```
+
+## Multi-Package Setup (Optional)
+
+For larger plugins, split into separate packages:
+
+```
+packages/
+├── plugin/              # @yourorg/my-plugin
+│   ├── src/
+│   ├── package.json
+│   └── tsconfig.json
+├── ui/                  # @yourorg/my-plugin-ui
+│   ├── src/
+│   ├── package.json
+│   └── vite.config.js
+└── core/                # @yourorg/my-plugin-core
+    ├── src/
+    ├── package.json
+    └── tsconfig.json
+```
+
+## Troubleshooting
+
+### Assets 404 Error
+
+**Problem:** UI loads but assets fail with 404
+
+**Fix:** Check `vite.config.js` has `base: ''` (NOT `base: './'`)
+
+### Plugin Not Found
+
+**Problem:** Plugin doesn't load in MAJK
+
+**Fix:**
+1. Ensure `dist/index.js` exists
+2. Check `package.json` has `"main": "dist/index.js"`
+3. Verify plugin calls `.build()` at the end
+
+### Generated Hooks Not Found
+
+**Problem:** `import { useHealth } from './generated/hooks'` fails
+
+**Fix:**
+1. Run `npm run build` to generate hooks
+2. Check `ui/src/generated/` directory exists
+3. Verify functions are defined before `.build()`
+
+### Tests Can't Find Plugin
+
+**Problem:** `invoke('functionName')` fails in tests
+
+**Fix:**
+1. Ensure plugin is built: `npm run build:plugin`
+2. Check function name matches definition
+3. Verify `export = plugin;` at end of `src/index.ts`
+
+## Quick Start Checklist
+
+- [ ] Create project structure
+- [ ] Add `vite.config.js` with `base: ''`
+- [ ] Add `tsconfig.json` for plugin and UI
+- [ ] Create `src/index.ts` with `definePlugin()`
+- [ ] Create `ui/src/App.tsx` with `BrowserRouter`
+- [ ] Add `.gitignore` to exclude `dist/` and `node_modules/`
+- [ ] Run `npm install` in root and `ui/`
+- [ ] Run `npm run build` to compile
+- [ ] Run `npm run test:plugin` to verify setup
+
+## Next Steps
+
+Run `npx @majkapp/plugin-kit --functions` - Define your functions
+Run `npx @majkapp/plugin-kit --screens` - Configure screens
+Run `npx @majkapp/plugin-kit --testing` - Write tests