@nsxbet/admin-sdk 0.2.1 → 0.5.0

package/CHECKLIST.md

@@ -0,0 +1,301 @@
+# 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
+
+- [ ] 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`
+- [ ] `postcss` — `^8.4.32`
+- [ ] `autoprefixer` — `^10.4.16`
+- [ ] `@nsxbet/eslint-plugin-admin` — (same version as SDK)
+
+## Vite Configuration
+
+- [ ] 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 (option A — full config):
+
+```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()],
+});
+```
+
+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`
+
+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
+}
+```
+
+## 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/**`
+- [ ] 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`
 
@@ -537,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";
@@ -545,26 +556,66 @@ 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
 });
 ```
 
-> **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.
 
-### Options
+#### `defineModuleConfig` Options
 
 | 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 |
 | `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):
@@ -573,6 +624,78 @@ 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:
+
+```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

@@ -1,13 +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
-     */
-    port: number;
+export interface AdminModuleOptions {
     /**
      * Entry file for the module SPA
      * @default "./src/spa.tsx"
@@ -22,6 +19,13 @@ export interface ModuleConfigOptions {
      * Additional externals to add to SHARED_EXTERNALS
      */
     additionalExternals?: string[];
+}
+export interface ModuleConfigOptions extends AdminModuleOptions {
+    /**
+     * Development server port
+     * @default 8080
+     */
+    port?: number;
     /**
      * Additional Vite plugins (will be spread into plugins array)
      */
@@ -31,17 +35,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;;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":"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;CAChC;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,CAwCtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,GAAG,CAiBpE"}

package/dist/vite/config.js

@@ -10,17 +10,80 @@ 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 = [], } = options;
+    const externals = [...SHARED_EXTERNALS, ...additionalExternals];
+    const buildConfigPlugin = {
+        name: "admin-module-build-config",
+        config(_config, { command }) {
+            if (command !== "build")
+                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 +111,13 @@ 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 externals = [...SHARED_EXTERNALS, ...additionalExternals];
+    const { port = 8080, plugins = [], overrides = {} } = options;
     return {
-        plugins: [
-            serveDistPlugin({ distDir: outDir }),
-            generateModuleManifestPlugin(),
-            ...plugins,
-        ],
+        plugins: [...adminModule(options), ...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.2.1",
+  "version": "0.5.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",
@@ -36,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",
@@ -47,6 +51,9 @@
     "@vitejs/plugin-react": {
       "optional": true
     },
+    "@vitejs/plugin-react-swc": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     }

package/scripts/postinstall.js

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