@nsxbet/admin-sdk 0.4.0 → 0.5.1

package/CHECKLIST.md

@@ -67,7 +67,7 @@ Expected structure:
 
 ### Dev Dependencies
 
-- [ ] `@vitejs/plugin-react` — `^4.2.1`
+- [ ] React plugin — either `@vitejs/plugin-react` `^4.2.1` OR `@vitejs/plugin-react-swc` `^3.0.0` (Lovable default)
 - [ ] `vite` — `^5.0.8`
 - [ ] `typescript` — `^5.2.2`
 - [ ] `tailwindcss` — `^3.4.0`
@@ -77,10 +77,10 @@ Expected structure:
 
 ## Vite Configuration
 
-- [ ] Imports `defineModuleConfig` from `@nsxbet/admin-sdk/vite`
-- [ ] Imports and uses `react()` from `@vitejs/plugin-react`
+- [ ] Uses `defineModuleConfig` from `@nsxbet/admin-sdk/vite` OR spreads `adminModule()` into an existing Vite config
+- [ ] Imports and uses a React plugin (`@vitejs/plugin-react` or `@vitejs/plugin-react-swc`)
 
-Expected:
+Expected (option A — full config):
 
 ```typescript
 import { defineModuleConfig } from "@nsxbet/admin-sdk/vite";
@@ -92,6 +92,18 @@ export default defineModuleConfig({
 });
 ```
 
+Expected (option B — composable plugin for Lovable / existing config):
+
+```typescript
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react-swc";
+import { adminModule } from "@nsxbet/admin-sdk/vite";
+
+export default defineConfig({
+  plugins: [react(), ...adminModule()],
+});
+```
+
 ## Tailwind Configuration
 
 - [ ] Imports `withAdminSdk` from `@nsxbet/admin-sdk/tailwind`
@@ -201,6 +213,83 @@ function MyComponent() {
 }
 ```
 
+## Lovable Projects (additional guidance)
+
+If your module was scaffolded by Lovable, the following differences apply:
+
+- [ ] `vite.config.ts` uses `adminModule()` spread into the existing plugins array (option B above), NOT `defineModuleConfig`
+- [ ] React plugin is `@vitejs/plugin-react-swc` (Lovable default) — this is supported
+- [ ] `index.html` entry point references `/src/main.tsx` (Lovable default) — this serves as the standalone dev entry
+- [ ] `src/main.tsx` wraps your App with `AdminShell` (same role as `src/standalone.tsx` in non-Lovable modules)
+- [ ] `src/spa.tsx` still required — `export default App` for shell mode
+- [ ] `admin.module.json` still required at project root
+- [ ] `module.manifest.json` is auto-generated at build time by `adminModule()` — do NOT manually copy `admin.module.json` to `dist/`
+- [ ] Lovable's existing `server`, `resolve.alias`, and plugin settings are preserved — `adminModule()` only affects `vite build`
+- [ ] Build script can be `"vite build"` (Lovable default) or `"tsc && vite build"` — both work
+
+Expected `vite.config.ts` for Lovable:
+
+```typescript
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react-swc";
+import path from "path";
+import { componentTagger } from "lovable-tagger";
+import { adminModule } from "@nsxbet/admin-sdk/vite";
+
+export default defineConfig(({ mode }) => ({
+  server: {
+    host: "::",
+    port: 8080,
+    hmr: { overlay: false },
+  },
+  plugins: [
+    react(),
+    mode === "development" && componentTagger(),
+    ...adminModule(),
+  ].filter(Boolean),
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+}));
+```
+
+Expected `src/main.tsx` for Lovable (standalone dev entry):
+
+```tsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+import {
+  AdminShell,
+  createInMemoryAuthClient,
+  createMockUsersFromRoles,
+} from "@nsxbet/admin-sdk";
+import type { AdminModuleManifest } from "@nsxbet/admin-sdk";
+import { App } from "./App";
+import manifest from "../admin.module.json";
+import "./index.css";
+
+const moduleManifest = manifest as AdminModuleManifest;
+
+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: [],
+});
+
+const authClient = createInMemoryAuthClient({ users: mockUsers });
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <AdminShell modules={[moduleManifest]} authClient={authClient}>
+      <App />
+    </AdminShell>
+  </React.StrictMode>
+);
+```
+
 ## Anti-Patterns (MUST NOT be present)
 
 - [ ] No `@supabase/supabase-js` or `supabase` imports in `src/**`

package/README.md

@@ -539,7 +539,16 @@ Use [Lucide](https://lucide.dev/icons) icon names in **kebab-case**:
 
 ## Vite Configuration
 
-The SDK provides `defineModuleConfig` to simplify Vite setup:
+The SDK provides two ways to configure Vite for admin modules:
+
+1. **`defineModuleConfig()`** — returns a complete Vite config. Best for new modules with no existing Vite setup.
+2. **`adminModule()`** — returns a `Plugin[]` you spread into an existing config. Best for Lovable projects or any existing Vite config.
+
+Both produce identical build artifacts. Both support `@vitejs/plugin-react` and `@vitejs/plugin-react-swc`.
+
+> **Note:** `module.manifest.json` is generated automatically at build time by both `defineModuleConfig` and `adminModule`. No manual `cp admin.module.json dist/` step is needed.
+
+### `defineModuleConfig()` — Full Config
 
 ```typescript
 import { defineModuleConfig } from "@nsxbet/admin-sdk/vite";
@@ -547,7 +556,7 @@ import react from "@vitejs/plugin-react";
 
 export default defineModuleConfig({
   port: 3003,
-  plugins: [react()], // REQUIRED: you must add the React plugin
+  plugins: [react()], // REQUIRED: you must add a React plugin
 });
 ```
 
@@ -556,7 +565,7 @@ export default defineModuleConfig({
 > - API: 4000
 > - Modules: 3002, 3003, 3004, etc.
 
-### Options
+#### `defineModuleConfig` Options
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
@@ -567,6 +576,46 @@ export default defineModuleConfig({
 | `additionalExternals` | string[] | `[]` | Extra externals |
 | `overrides` | object | `{}` | Override any Vite config |
 
+### `adminModule()` — Composable Plugin (Lovable / Custom Vite Config)
+
+Use `adminModule()` when you already have a `vite.config.ts` and want to add admin module support without replacing it. This is the recommended approach for **Lovable projects**.
+
+`adminModule()` only affects `vite build` — during `vite dev`, your app runs as a normal SPA with HMR working as expected.
+
+```typescript
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react-swc";
+import path from "path";
+import { componentTagger } from "lovable-tagger";
+import { adminModule } from "@nsxbet/admin-sdk/vite";
+
+export default defineConfig(({ mode }) => ({
+  server: {
+    host: "::",
+    port: 8080,
+    hmr: { overlay: false },
+  },
+  plugins: [
+    react(),
+    mode === "development" && componentTagger(),
+    ...adminModule(),
+  ].filter(Boolean),
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+}));
+```
+
+#### `adminModule` Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `entry` | string | `"./src/spa.tsx"` | Entry file path |
+| `outDir` | string | `"dist"` | Output directory |
+| `additionalExternals` | string[] | `[]` | Extra externals |
+
 ### Shared Externals
 
 These dependencies are provided by the shell (do not bundle them):
@@ -575,6 +624,65 @@ These dependencies are provided by the shell (do not bundle them):
 ["react", "react-dom", "react-router-dom", "i18next", "react-i18next"]
 ```
 
+### Getting Started in Lovable
+
+Lovable projects come with a default `vite.config.ts`, `index.html`, and `src/main.tsx` entry point. To turn a Lovable project into an admin module:
+
+1. **Install the SDK:**
+
+```bash
+npm install @nsxbet/admin-sdk @nsxbet/admin-ui
+```
+
+2. **Add `adminModule()` to your existing `vite.config.ts`:**
+
+```typescript
+import { adminModule } from "@nsxbet/admin-sdk/vite";
+
+// Inside your plugins array:
+plugins: [
+  react(),
+  mode === "development" && componentTagger(),
+  ...adminModule(),
+].filter(Boolean),
+```
+
+3. **Create `admin.module.json`** at the project root with your module metadata.
+
+4. **Create `src/spa.tsx`** — the shell entry point:
+
+```tsx
+import { App } from "./App";
+export default App;
+```
+
+5. **Update `src/main.tsx`** — wrap your app with `AdminShell` for standalone dev:
+
+```tsx
+import { AdminShell, createInMemoryAuthClient, createMockUsersFromRoles } from "@nsxbet/admin-sdk";
+import manifest from "../admin.module.json";
+import { App } from "./App";
+
+const mockUsers = createMockUsersFromRoles({
+  admin: ["admin.mymodule.view", "admin.mymodule.edit"],
+  editor: ["admin.mymodule.view", "admin.mymodule.edit"],
+  viewer: ["admin.mymodule.view"],
+  noAccess: [],
+});
+
+const authClient = createInMemoryAuthClient({ users: mockUsers });
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <AdminShell modules={[manifest]} authClient={authClient}>
+    <App />
+  </AdminShell>
+);
+```
+
+6. **Build:** `npm run build` produces `dist/assets/spa-[hash].js` + `dist/module.manifest.json`
+
+Your Lovable preview (`vite dev`) continues to work as before — `adminModule()` only changes the `vite build` output.
+
 ## ESLint Plugin
 
 Install `@nsxbet/eslint-plugin-admin` (requires ESLint 9+) to catch common mistakes at development time:

package/dist/vite/config.d.ts

@@ -1,14 +1,10 @@
+import type { Plugin } from "vite";
 /**
  * Shared dependencies that are externalized in module builds.
  * These are provided by the shell via import maps.
  */
 export declare const SHARED_EXTERNALS: readonly ["react", "react-dom", "react-router-dom", "i18next", "react-i18next"];
-export interface ModuleConfigOptions {
-    /**
-     * Development server port
-     * @default 8080
-     */
-    port?: number;
+export interface AdminModuleOptions {
     /**
      * Entry file for the module SPA
      * @default "./src/spa.tsx"
@@ -23,6 +19,21 @@ export interface ModuleConfigOptions {
      * Additional externals to add to SHARED_EXTERNALS
      */
     additionalExternals?: string[];
+    /**
+     * Controls when lib mode build config is applied.
+     * - "auto" (default): Only apply when ADMIN_MODULE=true env var is set.
+     *   Use this in Lovable projects so `vite build` produces a normal HTML SPA
+     *   and `vite build` with ADMIN_MODULE=true produces the module library entry.
+     * - "always": Always apply during `vite build`. Used by defineModuleConfig().
+     */
+    buildMode?: "auto" | "always";
+}
+export interface ModuleConfigOptions extends AdminModuleOptions {
+    /**
+     * Development server port
+     * @default 8080
+     */
+    port?: number;
     /**
      * Additional Vite plugins (will be spread into plugins array)
      */
@@ -32,17 +43,47 @@ export interface ModuleConfigOptions {
      */
     overrides?: Record<string, any>;
 }
+/**
+ * Composable Vite plugin array for admin modules.
+ * Returns plugins that handle build-time lib config, dist serving, and manifest generation.
+ *
+ * Use this when you already have a Vite config (e.g. Lovable) and want to add
+ * admin module support without replacing your entire config.
+ *
+ * The build config plugin only applies during `vite build` — dev server works as a normal SPA.
+ *
+ * @example In a Lovable project
+ * ```ts
+ * import { defineConfig } from "vite";
+ * import react from "@vitejs/plugin-react-swc";
+ * import { adminModule } from "@nsxbet/admin-sdk/vite";
+ *
+ * export default defineConfig(({ mode }) => ({
+ *   plugins: [
+ *     react(),
+ *     mode === "development" && componentTagger(),
+ *     ...adminModule(),
+ *   ].filter(Boolean),
+ * }));
+ * ```
+ *
+ * @example With custom entry and externals
+ * ```ts
+ * ...adminModule({
+ *   entry: "./src/custom-spa.tsx",
+ *   additionalExternals: ["lodash"],
+ * })
+ * ```
+ */
+export declare function adminModule(options?: AdminModuleOptions): Plugin[];
 /**
  * Creates a pre-configured Vite config for admin modules.
  *
  * **Note:** This function does NOT include the React plugin automatically.
  * You must import and add it yourself to avoid version conflicts.
  *
- * Includes:
- * - serveDistPlugin (serves dist files during dev)
- * - generateModuleManifestPlugin (generates module.manifest.json)
- * - ES module build format
- * - Externalized shared dependencies
+ * For Lovable or other existing Vite configs, use the composable `adminModule()` plugin
+ * instead — it can be spread into any existing plugins array.
  *
  * @example
  * ```ts

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;;;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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/vite/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC;;;GAGG;AACH,eAAO,MAAM,gBAAgB,iFAMnB,CAAC;AAEX,MAAM,WAAW,kBAAkB;IACjC;;;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;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IAEH,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;IAEhB;;OAEG;IAEH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,MAAM,EAAE,CA8CtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,GAAG,CAiBpE"}

package/dist/vite/config.js

@@ -10,17 +10,85 @@ export const SHARED_EXTERNALS = [
     "i18next",
     "react-i18next",
 ];
+/**
+ * Composable Vite plugin array for admin modules.
+ * Returns plugins that handle build-time lib config, dist serving, and manifest generation.
+ *
+ * Use this when you already have a Vite config (e.g. Lovable) and want to add
+ * admin module support without replacing your entire config.
+ *
+ * The build config plugin only applies during `vite build` — dev server works as a normal SPA.
+ *
+ * @example In a Lovable project
+ * ```ts
+ * import { defineConfig } from "vite";
+ * import react from "@vitejs/plugin-react-swc";
+ * import { adminModule } from "@nsxbet/admin-sdk/vite";
+ *
+ * export default defineConfig(({ mode }) => ({
+ *   plugins: [
+ *     react(),
+ *     mode === "development" && componentTagger(),
+ *     ...adminModule(),
+ *   ].filter(Boolean),
+ * }));
+ * ```
+ *
+ * @example With custom entry and externals
+ * ```ts
+ * ...adminModule({
+ *   entry: "./src/custom-spa.tsx",
+ *   additionalExternals: ["lodash"],
+ * })
+ * ```
+ */
+export function adminModule(options = {}) {
+    const { entry = "./src/spa.tsx", outDir = "dist", additionalExternals = [], buildMode = "auto", } = options;
+    const externals = [...SHARED_EXTERNALS, ...additionalExternals];
+    function isModuleBuild() {
+        if (buildMode === "always")
+            return true;
+        return process.env.ADMIN_MODULE === "true";
+    }
+    const buildConfigPlugin = {
+        name: "admin-module-build-config",
+        config(_config, { command }) {
+            if (command !== "build" || !isModuleBuild())
+                return;
+            return {
+                build: {
+                    outDir,
+                    emptyOutDir: true,
+                    lib: {
+                        entry,
+                        formats: ["es"],
+                        fileName: () => `assets/spa-[hash].js`,
+                    },
+                    rollupOptions: {
+                        external: externals,
+                        output: {
+                            entryFileNames: "assets/[name]-[hash].js",
+                            chunkFileNames: "assets/[name]-[hash].js",
+                        },
+                    },
+                },
+            };
+        },
+    };
+    return [
+        serveDistPlugin({ distDir: outDir }),
+        generateModuleManifestPlugin(),
+        buildConfigPlugin,
+    ];
+}
 /**
  * Creates a pre-configured Vite config for admin modules.
  *
  * **Note:** This function does NOT include the React plugin automatically.
  * You must import and add it yourself to avoid version conflicts.
  *
- * Includes:
- * - serveDistPlugin (serves dist files during dev)
- * - generateModuleManifestPlugin (generates module.manifest.json)
- * - ES module build format
- * - Externalized shared dependencies
+ * For Lovable or other existing Vite configs, use the composable `adminModule()` plugin
+ * instead — it can be spread into any existing plugins array.
  *
  * @example
  * ```ts
@@ -48,34 +116,13 @@ export const SHARED_EXTERNALS = [
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function defineModuleConfig(options) {
-    const { port = 8080, entry = "./src/spa.tsx", outDir = "dist", additionalExternals = [], plugins = [], overrides = {}, } = options;
-    const externals = [...SHARED_EXTERNALS, ...additionalExternals];
+    const { port = 8080, plugins = [], overrides = {} } = options;
     return {
-        plugins: [
-            serveDistPlugin({ distDir: outDir }),
-            generateModuleManifestPlugin(),
-            ...plugins,
-        ],
+        plugins: [...adminModule({ ...options, buildMode: "always" }), ...plugins],
         define: {
             "process.env": {},
             "process.env.NODE_ENV": JSON.stringify("production"),
         },
-        build: {
-            outDir,
-            emptyOutDir: true,
-            lib: {
-                entry,
-                formats: ["es"],
-                fileName: () => `assets/spa-[hash].js`,
-            },
-            rollupOptions: {
-                external: externals,
-                output: {
-                    entryFileNames: "assets/[name]-[hash].js",
-                    chunkFileNames: "assets/[name]-[hash].js",
-                },
-            },
-        },
         server: {
             port,
         },

package/dist/vite/index.d.ts

@@ -14,5 +14,5 @@
  * @packageDocumentation
  */
 export { generateModuleManifestPlugin, serveDistPlugin, type GenerateModuleManifestPluginOptions, type ServeDistPluginOptions, } from "./plugins.js";
-export { defineModuleConfig, SHARED_EXTERNALS, type ModuleConfigOptions, } from "./config.js";
+export { adminModule, defineModuleConfig, SHARED_EXTERNALS, type AdminModuleOptions, type ModuleConfigOptions, } from "./config.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,4BAA4B,EAC5B,eAAe,EACf,KAAK,mCAAmC,EACxC,KAAK,sBAAsB,GAC5B,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,4BAA4B,EAC5B,eAAe,EACf,KAAK,mCAAmC,EACxC,KAAK,sBAAsB,GAC5B,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC"}

package/dist/vite/index.js

@@ -14,4 +14,4 @@
  * @packageDocumentation
  */
 export { generateModuleManifestPlugin, serveDistPlugin, } from "./plugins.js";
-export { defineModuleConfig, SHARED_EXTERNALS, } from "./config.js";
+export { adminModule, defineModuleConfig, SHARED_EXTERNALS, } from "./config.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nsxbet/admin-sdk",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "SDK for building NSX Admin modules with integrated shell",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,6 +39,7 @@
   "peerDependencies": {
     "@nsxbet/admin-ui": "^0.2.0",
     "@vitejs/plugin-react": "^4.0.0",
+    "@vitejs/plugin-react-swc": "^3.0.0",
     "i18next": "^23.0.0 || ^24.0.0 || ^25.0.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
@@ -50,6 +51,9 @@
     "@vitejs/plugin-react": {
       "optional": true
     },
+    "@vitejs/plugin-react-swc": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     }