@nsxbet/admin-sdk 0.2.1 → 0.4.0

package/CHECKLIST.md

@@ -0,0 +1,212 @@
+# Admin Module Setup Checklist
+
+> Verify each item to ensure your module is correctly configured.
+> For module-specific values, run `npx adminx checklist` (requires `@nsxbet/admin-cli`).
+
+**Usage for LLMs:** Work through each section, check off items as you verify them. Compare your files against the expected content blocks.
+
+## Required Files
+
+- [ ] `admin.module.json` — Module manifest
+- [ ] `package.json` — Package configuration
+- [ ] `vite.config.ts` — Vite build config
+- [ ] `index.html` — HTML entry point
+- [ ] `src/spa.tsx` — Shell entry (default export)
+- [ ] `src/standalone.tsx` — Dev entry (AdminShell wrapper)
+- [ ] `src/App.tsx` — Main app component (Routes)
+- [ ] `src/index.css` — Styles with Tailwind directives
+- [ ] `tailwind.config.js` — Tailwind config
+- [ ] `postcss.config.js` — PostCSS config
+- [ ] `tsconfig.json` — TypeScript config
+- [ ] `tsconfig.node.json` — Node TypeScript config
+- [ ] `src/globals.d.ts` — Global type declarations
+
+## Module Manifest (`admin.module.json`)
+
+- [ ] Has `id` field (format: `@admin/<name>`)
+- [ ] Has `title` field
+- [ ] Has `routeBase` field (starts with `/`)
+- [ ] Has `description` field (recommended)
+- [ ] Has `version` field (recommended)
+- [ ] Has `category` field (recommended)
+- [ ] Has `permissions` object (recommended, values are string arrays)
+- [ ] Has `commands` array (recommended, each with `id`, `title`, `route`)
+- [ ] All command `route` values start with the module's `routeBase`
+
+Expected structure:
+
+```json
+{
+  "id": "@admin/my-module",
+  "title": "My Module",
+  "routeBase": "/my-module",
+  "description": "My Module admin module",
+  "version": "1.0.0",
+  "category": "Tools",
+  "commands": [{ "id": "home", "title": "Home", "route": "/my-module/home" }],
+  "permissions": {
+    "view": ["admin.my-module.view"],
+    "edit": ["admin.my-module.edit"],
+    "delete": ["admin.my-module.delete"]
+  }
+}
+```
+
+## Dependencies (`package.json`)
+
+- [ ] `"type": "module"` is set
+- [ ] Build script is `"tsc && vite build"`
+
+### Runtime Dependencies
+
+- [ ] `@nsxbet/admin-sdk` — `workspace:*` or git tag version
+- [ ] `@nsxbet/admin-ui` — `workspace:*` or git tag version
+- [ ] `react` — `^18.2.0`
+- [ ] `react-dom` — `^18.2.0`
+- [ ] `react-router-dom` — `^6.20.1`
+
+### Dev Dependencies
+
+- [ ] `@vitejs/plugin-react` — `^4.2.1`
+- [ ] `vite` — `^5.0.8`
+- [ ] `typescript` — `^5.2.2`
+- [ ] `tailwindcss` — `^3.4.0`
+- [ ] `postcss` — `^8.4.32`
+- [ ] `autoprefixer` — `^10.4.16`
+- [ ] `@nsxbet/eslint-plugin-admin` — (same version as SDK)
+
+## Vite Configuration
+
+- [ ] Imports `defineModuleConfig` from `@nsxbet/admin-sdk/vite`
+- [ ] Imports and uses `react()` from `@vitejs/plugin-react`
+
+Expected:
+
+```typescript
+import { defineModuleConfig } from "@nsxbet/admin-sdk/vite";
+import react from "@vitejs/plugin-react";
+
+export default defineModuleConfig({
+  port: 3003, // Choose a unique port for your module
+  plugins: [react()],
+});
+```
+
+## Tailwind Configuration
+
+- [ ] Imports `withAdminSdk` from `@nsxbet/admin-sdk/tailwind`
+
+Expected:
+
+```javascript
+import { withAdminSdk } from "@nsxbet/admin-sdk/tailwind";
+
+export default withAdminSdk({
+  content: ["./index.html", "./src/**/*.{ts,tsx}"],
+});
+```
+
+## PostCSS Configuration
+
+- [ ] Has `tailwindcss` and `autoprefixer` plugins
+
+Expected:
+
+```javascript
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
+```
+
+## CSS Setup (`src/index.css`)
+
+- [ ] Imports `@nsxbet/admin-ui/styles.css`
+- [ ] Has `@tailwind base`, `@tailwind components`, `@tailwind utilities`
+
+Expected:
+
+```css
+@import "@nsxbet/admin-ui/styles.css";
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+## Entry Points
+
+### `src/spa.tsx`
+
+- [ ] Has `export default` (the App component)
+
+Expected:
+
+```tsx
+import { App } from "./App";
+
+export default App;
+```
+
+### `src/standalone.tsx`
+
+- [ ] Uses `AdminShell` from `@nsxbet/admin-sdk`
+- [ ] Imports manifest and passes to `modules` prop
+- [ ] Permissions use namespace `admin.<module-name>.*`
+
+Expected (simplified):
+
+```tsx
+import { AdminShell } from "@nsxbet/admin-sdk";
+import manifest from "../admin.module.json";
+import { App } from "./App";
+
+<AdminShell modules={[manifest]} keycloak={config}>
+  <App />
+</AdminShell>
+```
+
+### `src/App.tsx`
+
+- [ ] Uses `<Routes>` from `react-router-dom`
+
+Expected:
+
+```tsx
+import { Routes, Route, Navigate } from "react-router-dom";
+
+export function App() {
+  return (
+    <Routes>
+      <Route path="/" element={<Navigate to="home" replace />} />
+      <Route path="home" element={<HomePage />} />
+    </Routes>
+  );
+}
+```
+
+## SDK Hook Usage
+
+```tsx
+import { useAuth, useFetch, useTelemetry } from "@nsxbet/admin-sdk";
+import { useNavigate } from "react-router-dom";
+
+function MyComponent() {
+  const { hasPermission, getUser } = useAuth();
+  const fetch = useFetch(); // Use this instead of raw fetch()
+  const { track } = useTelemetry();
+  const navigate = useNavigate(); // From react-router-dom, NOT from SDK
+}
+```
+
+## Anti-Patterns (MUST NOT be present)
+
+- [ ] No `@supabase/supabase-js` or `supabase` imports in `src/**`
+- [ ] No `firebase` imports in `src/**`
+- [ ] No `BrowserRouter` or `MemoryRouter` in `src/**` (except `standalone.tsx`)
+- [ ] No `useNavigate` imported from `@nsxbet/admin-sdk` (use `react-router-dom`)
+- [ ] No `@supabase/supabase-js` or `firebase` in `package.json` dependencies
+- [ ] No raw `fetch()` or `window.fetch()` calls — use `useFetch()` from the SDK
+- [ ] Do NOT scaffold shadcn/ui components locally — use `@nsxbet/admin-ui` which ships them pre-configured

package/README.md

@@ -45,6 +45,8 @@ The CLI scaffolds all 13 required files with correct configuration, dependency v
 
 > **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.
 
+> **Static checklist:** A ready-to-use `CHECKLIST.md` is also shipped inside the SDK package at `node_modules/@nsxbet/admin-sdk/CHECKLIST.md`. You can use it directly without installing the CLI.
+
 ## 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.
@@ -354,7 +356,7 @@ export default withAdminSdk({
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "tsc && vite build && cp admin.module.json dist/",
+    "build": "tsc && vite build",
     "preview": "vite preview"
   },
   "dependencies": {
@@ -382,7 +384,7 @@ export default withAdminSdk({
 
 > **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.
+> **Note:** `module.manifest.json` is generated automatically by `defineModuleConfig` at build time. No manual copy step is needed.
 
 ### File: `tsconfig.json`
 
@@ -549,7 +551,7 @@ export default defineModuleConfig({
 });
 ```
 
-> **Important:** Each module must use a unique port. Standard assignments:
+> **Important:** Each module must use a unique port. The default is `8080` (matching Lovable's default). Modules running alongside Keycloak (which also uses port 8080) should specify an explicit port. Standard assignments:
 > - Shell: 3000
 > - API: 4000
 > - Modules: 3002, 3003, 3004, etc.
@@ -558,7 +560,7 @@ export default defineModuleConfig({
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `port` | number | **required** | Dev server port |
+| `port` | number | `8080` | Dev server port |
 | `entry` | string | `"./src/spa.tsx"` | Entry file path |
 | `outDir` | string | `"dist"` | Output directory |
 | `plugins` | Plugin[] | `[]` | Additional Vite plugins |
@@ -573,6 +575,19 @@ These dependencies are provided by the shell (do not bundle them):
 ["react", "react-dom", "react-router-dom", "i18next", "react-i18next"]
 ```
 
+## ESLint Plugin
+
+Install `@nsxbet/eslint-plugin-admin` (requires ESLint 9+) to catch common mistakes at development time:
+
+```javascript
+// eslint.config.js
+import adminPlugin from "@nsxbet/eslint-plugin-admin";
+
+export default [adminPlugin.configs.recommended];
+```
+
+This enables all recommended rules including `@nsxbet/no-raw-fetch` which flags direct `fetch()`/`window.fetch()` calls that bypass authentication. Use `useFetch()` from the SDK instead.
+
 ## SDK Hooks
 
 ### `useAuth()`

package/dist/vite/config.d.ts

@@ -6,8 +6,9 @@ export declare const SHARED_EXTERNALS: readonly ["react", "react-dom", "react-ro
 export interface ModuleConfigOptions {
     /**
      * Development server port
+     * @default 8080
      */
-    port: number;
+    port?: number;
     /**
      * Entry file for the module SPA
      * @default "./src/spa.tsx"

package/dist/vite/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/vite/config.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,gBAAgB,iFAMnB,CAAC;AAEX,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE/B;;OAEG;IAEH,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;IAEhB;;OAEG;IAEH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,GAAG,CA8CpE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/vite/config.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,gBAAgB,iFAMnB,CAAC;AAEX,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE/B;;OAEG;IAEH,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;IAEhB;;OAEG;IAEH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,GAAG,CA8CpE"}

package/dist/vite/config.js

@@ -48,7 +48,7 @@ export const SHARED_EXTERNALS = [
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function defineModuleConfig(options) {
-    const { port, entry = "./src/spa.tsx", outDir = "dist", additionalExternals = [], plugins = [], overrides = {}, } = options;
+    const { port = 8080, entry = "./src/spa.tsx", outDir = "dist", additionalExternals = [], plugins = [], overrides = {}, } = options;
     const externals = [...SHARED_EXTERNALS, ...additionalExternals];
     return {
         plugins: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nsxbet/admin-sdk",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "SDK for building NSX Admin modules with integrated shell",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,9 +25,12 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHECKLIST.md",
+    "scripts"
   ],
   "scripts": {
+    "postinstall": "node scripts/postinstall.js",
     "build": "tsc",
     "dev": "tsc --watch --preserveWatchOutput",
     "type-check": "tsc --noEmit",

package/scripts/postinstall.js

@@ -0,0 +1 @@
+console.log("@nsxbet/admin-sdk: Module setup checklist available at node_modules/@nsxbet/admin-sdk/CHECKLIST.md");