@nsxbet/admin-sdk 0.6.0 → 0.7.0

package/CHECKLIST.md

@@ -256,6 +256,18 @@ If your module was scaffolded by Lovable, the following differences apply:
 - [ ] 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
 
+### Environment Configuration (automatic)
+
+`adminModule()` automatically injects `VITE_ADMIN_GATEWAY_URL` with the staging gateway URL (`https://admin-bff-stg.nsx.dev`). No `.env.staging` file or `--mode staging` script is needed for Lovable projects.
+
+- [ ] Do NOT create `.env.staging` — the Vite plugin handles it
+- [ ] Do NOT add `--mode staging` to the dev script
+
+To override the gateway URL, either:
+- Set `VITE_ADMIN_GATEWAY_URL` in a `.env` or `.env.local` file
+- Pass `gatewayUrl` option: `...adminModule({ gatewayUrl: "http://localhost:8080" })`
+- Disable injection: `...adminModule({ gatewayUrl: null })`
+
 Expected `vite.config.ts` for Lovable:
 
 ```typescript

package/README.md

@@ -676,6 +676,38 @@ export default defineConfig(({ mode }) => ({
 | `entry` | string | `"./src/spa.tsx"` | Entry file path |
 | `outDir` | string | `"dist"` | Output directory |
 | `additionalExternals` | string[] | `[]` | Extra externals |
+| `gatewayUrl` | `string \| null` | `undefined` | Admin gateway URL for env injection. `undefined` = auto-inject staging URL, `string` = inject custom URL, `null` = disable injection. Explicit env vars always take precedence. |
+
+### Automatic Environment Injection
+
+`adminModule()` includes an env injection plugin that automatically sets `VITE_ADMIN_GATEWAY_URL` at build time. This ensures Lovable projects get real JWT tokens from the staging gateway without any manual `.env` configuration.
+
+**Precedence order** (highest to lowest):
+
+1. Explicit env var (`.env`, `.env.local`, shell environment)
+2. `gatewayUrl` option passed to `adminModule()` or `defineModuleConfig()`
+3. Default: `https://admin-bff-stg.nsx.dev` (staging)
+
+**Known gateway URLs:**
+
+| Environment | URL |
+|---|---|
+| Staging | `https://admin-bff-stg.nsx.dev` |
+| Homol | `https://admin-bff-homol.nsx.dev` |
+| Local | `http://localhost:8080` |
+
+**Examples:**
+
+```ts
+// Default: staging URL auto-injected
+...adminModule()
+
+// Custom URL
+...adminModule({ gatewayUrl: "http://localhost:8080" })
+
+// Disable injection entirely
+...adminModule({ gatewayUrl: null })
+```
 
 ### Shared Externals
 
@@ -1103,6 +1135,8 @@ When `VITE_ADMIN_GATEWAY_URL` is set (or `gatewayUrl` is passed explicitly), the
 2. `import.meta.env.VITE_ADMIN_GATEWAY_URL` environment variable
 3. If neither is set, BFF integration is disabled (mock tokens, current behavior)
 
+> **Vite plugin auto-injection:** When using `adminModule()` or `defineModuleConfig()` from `@nsxbet/admin-sdk/vite`, the `VITE_ADMIN_GATEWAY_URL` environment variable is automatically set to the staging gateway URL. No `.env.staging` file or `--mode staging` script is needed. See the [Vite Configuration](#vite-configuration) section for override options.
+
 **Error handling:**
 
 The UserSelector shows loading, error, and timeout states during the token fetch. If the gateway is unreachable, the developer can:

package/dist/vite/config.d.ts

@@ -1,4 +1,9 @@
-import type { Plugin } from "vite";
+import { type Plugin } from "vite";
+/**
+ * Default admin gateway URL (staging environment).
+ * Used by the env injection plugin when no explicit value is configured.
+ */
+export declare const ADMIN_GATEWAY_STAGING_URL = "https://admin-bff-stg.nsx.dev";
 /**
  * Shared dependencies that are externalized in module builds.
  * These are provided by the shell via import maps.
@@ -28,6 +33,15 @@ export interface AdminModuleOptions {
      * - "always": Always apply during `vite build`. Used by defineModuleConfig().
      */
     buildMode?: "auto" | "always";
+    /**
+     * Admin gateway URL for BFF token integration (InMemory auth).
+     * - `undefined` (default): auto-inject staging URL (`https://admin-bff-stg.nsx.dev`)
+     * - `string`: inject the provided URL
+     * - `null`: disable automatic injection entirely
+     *
+     * Explicit env vars (`.env` files, shell env) always take precedence over this option.
+     */
+    gatewayUrl?: string | null;
 }
 export interface ModuleConfigOptions extends AdminModuleOptions {
     /**

package/dist/vite/config.js

@@ -1,6 +1,13 @@
+import { loadEnv } from "vite";
 import { generateModuleManifestPlugin, serveDistPlugin } from "./plugins.js";
 import { adminModuleI18nPlugin } from "./i18n-plugin.js";
 import { getSharedExternals } from "./AdminShellSharedDeps.js";
+const ENV_KEY = "VITE_ADMIN_GATEWAY_URL";
+/**
+ * Default admin gateway URL (staging environment).
+ * Used by the env injection plugin when no explicit value is configured.
+ */
+export const ADMIN_GATEWAY_STAGING_URL = "https://admin-bff-stg.nsx.dev";
 /**
  * Shared dependencies that are externalized in module builds.
  * These are provided by the shell via import maps.
@@ -40,13 +47,33 @@ export const SHARED_EXTERNALS = getSharedExternals();
  * ```
  */
 export function adminModule(options = {}) {
-    const { entry = "./src/spa.tsx", outDir = "dist", additionalExternals = [], buildMode = "auto", } = options;
+    const { entry = "./src/spa.tsx", outDir = "dist", additionalExternals = [], buildMode = "auto", gatewayUrl, } = options;
     const externals = [...SHARED_EXTERNALS, ...additionalExternals];
     function isModuleBuild() {
         if (buildMode === "always")
             return true;
         return process.env.ADMIN_MODULE === "true";
     }
+    const envPlugin = {
+        name: "admin-module-env",
+        config(_config, { mode }) {
+            if (gatewayUrl === null)
+                return;
+            const env = loadEnv(mode, process.cwd(), "VITE_");
+            const fromEnv = process.env[ENV_KEY] || env[ENV_KEY];
+            if (fromEnv) {
+                console.log(`[admin-module-env] ${ENV_KEY} → ${fromEnv} (from env)`);
+                return;
+            }
+            const url = gatewayUrl ?? ADMIN_GATEWAY_STAGING_URL;
+            console.log(`[admin-module-env] ${ENV_KEY} → ${url} (auto-injected)`);
+            return {
+                define: {
+                    [`import.meta.env.${ENV_KEY}`]: JSON.stringify(url),
+                },
+            };
+        },
+    };
     const buildConfigPlugin = {
         name: "admin-module-build-config",
         config(_config, { command }) {
@@ -73,6 +100,7 @@ export function adminModule(options = {}) {
         },
     };
     return [
+        envPlugin,
         adminModuleI18nPlugin(),
         serveDistPlugin({ distDir: outDir }),
         generateModuleManifestPlugin(),

package/dist/vite/index.d.ts

@@ -15,5 +15,5 @@
  */
 export { generateModuleManifestPlugin, serveDistPlugin, type GenerateModuleManifestPluginOptions, type ServeDistPluginOptions, } from "./plugins.js";
 export { adminModuleI18nPlugin, type AdminModuleI18nPluginOptions, } from "./i18n-plugin.js";
-export { adminModule, defineModuleConfig, SHARED_EXTERNALS, type AdminModuleOptions, type ModuleConfigOptions, } from "./config.js";
+export { adminModule, defineModuleConfig, SHARED_EXTERNALS, ADMIN_GATEWAY_STAGING_URL, type AdminModuleOptions, type ModuleConfigOptions, } from "./config.js";
 export { AdminShellSharedDeps, SHARED_DEPS_CONFIG, getSharedExternals, type SharedDepConfig, } from "./AdminShellSharedDeps.js";

package/dist/vite/index.js

@@ -15,5 +15,5 @@
  */
 export { generateModuleManifestPlugin, serveDistPlugin, } from "./plugins.js";
 export { adminModuleI18nPlugin, } from "./i18n-plugin.js";
-export { adminModule, defineModuleConfig, SHARED_EXTERNALS, } from "./config.js";
+export { adminModule, defineModuleConfig, SHARED_EXTERNALS, ADMIN_GATEWAY_STAGING_URL, } from "./config.js";
 export { AdminShellSharedDeps, SHARED_DEPS_CONFIG, getSharedExternals, } from "./AdminShellSharedDeps.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nsxbet/admin-sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "SDK for building NSX Admin modules with integrated shell",
   "type": "module",
   "main": "./dist/index.js",