@nsxbet/admin-sdk 0.2.0 → 0.2.1

package/README.md

@@ -8,13 +8,43 @@ SDK for building admin modules for the NSX Admin platform.
 bun add @nsxbet/admin-sdk @nsxbet/admin-ui
 ```
 
-**Peer dependencies** (install these too):
+**Peer dependencies:**
 
 ```bash
-bun add react react-dom react-router-dom i18next react-i18next
-bun add -D @vitejs/plugin-react vite tailwindcss postcss autoprefixer typescript
+# Shared with shell - use exact versions to avoid conflicts
+bun add react@18.2.0 react-dom@18.2.0 react-router-dom@6.20.1 i18next@25.0.0 react-i18next@16.0.0
+
+# Styling - use exact versions for design system consistency
+bun add -D tailwindcss@3.4.0 postcss@8.4.32 autoprefixer@10.4.16 tailwindcss-animate@1.0.7
+
+# Build tools - flexible versions are fine
+bun add -D @vitejs/plugin-react vite typescript
+```
+
+> **Why exact versions?** React, React Router, and i18next are shared at runtime - mismatches cause conflicts. Tailwind/PostCSS versions ensure consistent styling with the design system.
+
+## Quick Start (CLI)
+
+The fastest way to create a new module is using the CLI:
+
+```bash
+# Scaffold a new module
+npx @nsxbet/admin-cli init --id "@admin/my-module" --title "My Module" --route "/my-module" --port 3010
+
+# Generate a setup verification checklist
+npx @nsxbet/admin-cli checklist --output CHECKLIST.md
+
+# Validate an existing module
+npx @nsxbet/admin-cli check
+
+# Auto-fix common issues
+npx @nsxbet/admin-cli check --fix
 ```
 
+The CLI scaffolds all 13 required files with correct configuration, dependency versions, and SDK integration. It also validates existing modules against the canonical reference.
+
+> **Required for LLMs:** After creating or modifying a module, run `npx @nsxbet/admin-cli checklist --output CHECKLIST.md` and verify every item in the generated file before considering the setup complete. The checklist is a self-contained verification guide—no CLI installation needed to consume it.
+
 ## Quick Start
 
 This SDK enables you to build admin modules that integrate with the NSX Admin shell. Modules are loaded dynamically via React.lazy and share the shell's Router context.
@@ -115,7 +145,13 @@ export default App;
 ```tsx
 import React from "react";
 import ReactDOM from "react-dom/client";
-import { AdminShell, initI18n, i18n } from "@nsxbet/admin-sdk";
+import {
+  AdminShell,
+  initI18n,
+  i18n,
+  createInMemoryAuthClient,
+  createMockUsersFromRoles,
+} from "@nsxbet/admin-sdk";
 import type { AdminModuleManifest } from "@nsxbet/admin-sdk";
 import { App } from "./App";
 import manifest from "../admin.module.json";
@@ -134,9 +170,40 @@ const NAMESPACE = "mymodule";
 i18n.addResourceBundle("en-US", NAMESPACE, enUS, true, true);
 i18n.addResourceBundle("pt-BR", NAMESPACE, ptBR, true, true);
 
+// Type assertion for JSON import
+const moduleManifest = manifest as AdminModuleManifest;
+
+// Check environment variable to toggle between mock auth and Keycloak
+const useKeycloak = import.meta.env.VITE_MOCK_AUTH === "false";
+
+// Create mock users with module-specific permissions
+const mockUsers = createMockUsersFromRoles({
+  admin: ["admin.mymodule.view", "admin.mymodule.edit", "admin.mymodule.delete"],
+  editor: ["admin.mymodule.view", "admin.mymodule.edit"],
+  viewer: ["admin.mymodule.view"],
+  noAccess: [],
+});
+
+// Use in-memory auth by default (shows user selector), or Keycloak if configured
+const authClient = useKeycloak
+  ? undefined
+  : createInMemoryAuthClient({ users: mockUsers });
+
 ReactDOM.createRoot(document.getElementById("root")!).render(
   <React.StrictMode>
-    <AdminShell modules={[manifest as AdminModuleManifest]}>
+    <AdminShell
+      modules={[moduleManifest]}
+      authClient={authClient}
+      keycloak={
+        useKeycloak
+          ? {
+              url: "http://localhost:8080",
+              realm: "admin",
+              clientId: "admin-shell",
+            }
+          : undefined
+      }
+    >
       <App />
     </AdminShell>
   </React.StrictMode>
@@ -219,6 +286,52 @@ export function ItemList() {
 @tailwind utilities;
 ```
 
+### Directory: `src/i18n/` (optional - for translations)
+
+Structure:
+
+```
+src/i18n/
+  locales/
+    en-US.json    # English (required)
+    pt-BR.json    # Portuguese
+```
+
+Example `src/i18n/locales/en-US.json`:
+
+```json
+{
+  "module": {
+    "title": "My Module",
+    "description": "Description of my module"
+  },
+  "list": {
+    "title": "All Items",
+    "noItems": "No items found.",
+    "create": "Create Item"
+  },
+  "form": {
+    "titleLabel": "Title",
+    "titlePlaceholder": "Enter title",
+    "cancel": "Cancel",
+    "submit": "Submit"
+  }
+}
+```
+
+Use translations in components:
+
+```tsx
+import { useI18n } from "@nsxbet/admin-sdk";
+
+function MyComponent() {
+  const { t } = useI18n();
+  
+  // Use with namespace prefix (set in standalone.tsx)
+  return <h1>{t("mymodule:list.title")}</h1>;
+}
+```
+
 ### File: `tailwind.config.js`
 
 Use `withAdminSdk` which automatically includes the UI preset and SDK/UI content paths:
@@ -247,25 +360,30 @@ export default withAdminSdk({
   "dependencies": {
     "@nsxbet/admin-sdk": "latest",
     "@nsxbet/admin-ui": "latest",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "react-router-dom": "^6.20.0",
-    "i18next": "^25.0.0",
-    "react-i18next": "^16.0.0"
+    "react": "18.2.0",
+    "react-dom": "18.2.0",
+    "react-router-dom": "6.20.1",
+    "i18next": "25.0.0",
+    "react-i18next": "16.0.0"
   },
   "devDependencies": {
     "@types/react": "^18.2.0",
     "@types/react-dom": "^18.2.0",
     "@vitejs/plugin-react": "^4.2.0",
-    "autoprefixer": "^10.4.16",
-    "postcss": "^8.4.32",
-    "tailwindcss": "^3.4.0",
+    "autoprefixer": "10.4.16",
+    "postcss": "8.4.32",
+    "tailwindcss": "3.4.0",
+    "tailwindcss-animate": "1.0.7",
     "typescript": "^5.2.0",
     "vite": "^5.0.0"
   }
 }
 ```
 
+> **Note:** Exact versions for runtime deps (react, i18next) avoid conflicts with the shell. Exact versions for styling (tailwindcss, postcss) ensure design system consistency.
+
+> **Note:** The build script copies `admin.module.json` to `dist/` because the shell needs the manifest to register your module.
+
 ### File: `tsconfig.json`
 
 ```json
@@ -319,6 +437,66 @@ export default {
 };
 ```
 
+### File: `src/globals.d.ts`
+
+TypeScript declarations for environment variables and platform API:
+
+```typescript
+/// <reference types="vite/client" />
+
+declare global {
+  interface ImportMetaEnv {
+    readonly VITE_MOCK_AUTH?: string;
+  }
+
+  interface ImportMeta {
+    readonly env: ImportMetaEnv;
+  }
+
+  interface Window {
+    __ADMIN_PLATFORM_API__?: import("@nsxbet/admin-sdk").PlatformAPI;
+    __ENV__?: {
+      ENVIRONMENT: string;
+      KEYCLOAK_URL: string;
+      KEYCLOAK_REALM: string;
+      KEYCLOAK_CLIENT_ID: string;
+    };
+  }
+}
+
+export {};
+```
+
+### File: `tsconfig.node.json`
+
+Separate TypeScript config for Vite configuration file:
+
+```json
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true,
+    "strict": true
+  },
+  "include": ["vite.config.ts"]
+}
+```
+
+### File: `.env.local` (optional)
+
+Environment configuration for development:
+
+```bash
+# Use mock authentication with user selector (default: true)
+VITE_MOCK_AUTH=true
+
+# Set to "false" to use Keycloak authentication
+# VITE_MOCK_AUTH=false
+```
+
 ## Manifest Schema (`admin.module.json`)
 
 | Field | Type | Required | Description |
@@ -371,6 +549,11 @@ export default defineModuleConfig({
 });
 ```
 
+> **Important:** Each module must use a unique port. Standard assignments:
+> - Shell: 3000
+> - API: 4000
+> - Modules: 3002, 3003, 3004, etc.
+
 ### Options
 
 | Option | Type | Default | Description |
@@ -587,6 +770,50 @@ const authClient = createInMemoryAuthClient({ users: customUsers });
 | `users` | MockUser[] | **required** | Mock users available for selection |
 | `storageKey` | string | `"@nsxbet/auth"` | localStorage key for persistence |
 
+## Keycloak Configuration (Production Auth)
+
+For production or when testing with real authentication, configure Keycloak:
+
+### Prerequisites
+
+1. Keycloak server running (default: `http://localhost:8080`)
+2. Realm named `admin` created
+3. Client named `admin-shell` configured with:
+   - Client Protocol: `openid-connect`
+   - Access Type: `public`
+   - Valid Redirect URIs: `http://localhost:3003/*`
+
+### Enable Keycloak in Development
+
+Set the environment variable in `.env.local`:
+
+```bash
+VITE_MOCK_AUTH=false
+```
+
+Or pass the `keycloak` prop directly without `authClient`:
+
+```tsx
+<AdminShell
+  modules={[manifest]}
+  keycloak={{
+    url: "http://localhost:8080",
+    realm: "admin",
+    clientId: "admin-shell",
+  }}
+>
+  <App />
+</AdminShell>
+```
+
+### Keycloak Configuration Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `url` | string | Keycloak server URL |
+| `realm` | string | Realm name |
+| `clientId` | string | Client ID |
+
 ## DO NOT (Common Mistakes)
 
 ### ❌ DO NOT use MemoryRouter
@@ -690,6 +917,8 @@ import { useNavigate } from "react-router-dom"; // ✅
 
 ## Troubleshooting
 
+**First step:** Run `npx @nsxbet/admin-cli checklist` and verify all items. The checklist covers every setup requirement and often identifies misconfigurations quickly.
+
 ### "Failed to resolve module specifier 'react'"
 
 **Cause:** Module is bundling React instead of using shell's version.
@@ -719,7 +948,7 @@ define: {
 
 ### Styles not working
 
-**Checklist:**
+Run `npx @nsxbet/admin-cli checklist` to verify Tailwind/PostCSS configuration. Key items:
 1. ✅ `index.css` imports `@nsxbet/admin-ui/styles.css`
 2. ✅ `tailwind.config.js` uses `withAdminSdk` from `@nsxbet/admin-sdk/tailwind`
 3. ✅ `postcss.config.js` exists with tailwindcss plugin

package/dist/registry/client/http.d.ts

@@ -2,7 +2,7 @@
  * HTTP Registry Client
  *
  * Implementation of RegistryClient that communicates with the admin-api.
- * Used when running with PostgreSQL backend.
+ * Used when running with MySQL backend.
  */
 import type { RegistryClient } from './interface';
 /**

package/dist/registry/client/http.js

@@ -2,7 +2,7 @@
  * HTTP Registry Client
  *
  * Implementation of RegistryClient that communicates with the admin-api.
- * Used when running with PostgreSQL backend.
+ * Used when running with MySQL backend.
  */
 /**
  * Create an HTTP registry client

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nsxbet/admin-sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "SDK for building NSX Admin modules with integrated shell",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,7 +34,7 @@
     "test": "vitest run --passWithNoTests"
   },
   "peerDependencies": {
-    "@nsxbet/admin-ui": ">=0.1.0",
+    "@nsxbet/admin-ui": "^0.2.0",
     "@vitejs/plugin-react": "^4.0.0",
     "i18next": "^23.0.0 || ^24.0.0 || ^25.0.0",
     "react": "^18.2.0",