@lenne.tech/nuxt-extensions 1.8.1 → 1.8.2

package/CLAUDE.md

@@ -12,7 +12,7 @@ src/
 │   ├── components/        # Auto-imported components
 │   ├── lib/               # Library exports (auth-client, auth-state, ai)
 │   ├── middleware/        # Route middleware (system setup)
-│   ├── plugins/           # Nuxt plugins (auth interceptor, error translation)
+│   ├── plugins/           # Nuxt plugins (auth interceptor, error translation, config check)
 │   ├── server/            # Nitro server routes (auth proxy)
 │   ├── testing/           # Playwright test helpers
 │   ├── types/             # TypeScript type definitions

package/README.md

@@ -55,14 +55,16 @@ npm install tus-js-client
 All environment variables are resolved **at runtime** (not build time). This means you can build a Docker image once and deploy it to different environments by changing env vars — no rebuild needed.
 
 **SSR fallback chain:**
-`NUXT_API_URL` → `NUXT_PUBLIC_API_URL` → `auth.baseURL` (from nuxt.config.ts) → `http://localhost:3000`
+`NUXT_API_URL` → `NUXT_PUBLIC_API_URL` → `auth.baseURL` (from nuxt.config.ts) → *(unset)*
 
 **Client fallback chain (no proxy):**
-`NUXT_PUBLIC_API_URL` → `auth.baseURL` (from nuxt.config.ts) → `http://localhost:3000`
+`NUXT_PUBLIC_API_URL` → `auth.baseURL` (from nuxt.config.ts) → *(unset)*
 
 **Client with proxy (`NUXT_PUBLIC_API_PROXY=true`):**
 All requests go to `/api/{path}` — the Vite dev proxy forwards them to the backend.
 
+> **No implicit `localhost` default.** If none of the sources above is set, there is **no** built-in fallback URL: API paths stay relative (e.g. `/iam/token`) and resolve against the app origin, so auth and setup calls 404 unless the app is served behind a same-origin reverse proxy. The module logs a one-time warning (`[LtExtensions] No API URL configured…`) at app init and on the first API call. Always set `NUXT_PUBLIC_API_URL` (and optionally `NUXT_API_URL` for SSR).
+
 > **Security:** `NUXT_API_URL` is never exposed to the client bundle. It stays in `runtimeConfig.apiUrl` (server only). This is important when using internal network addresses like `http://api.svc.cluster.local`.
 
 ### Deployment Scenarios

package/dist/module.mjs

@@ -170,6 +170,7 @@ const module$1 = defineNuxtModule({
         filePath: resolve(`./runtime/components/transition/${componentName}.vue`)
       });
     }
+    addPlugin(resolve("./runtime/plugins/lt-config-check"));
     if (resolvedOptions.auth?.enabled && resolvedOptions.auth?.interceptor?.enabled) {
       addPlugin(resolve("./runtime/plugins/auth-interceptor.client"));
     }

package/dist/runtime/lib/auth-state.d.ts

@@ -90,6 +90,14 @@ export declare function getLtAuthCookieNames(): {
  * unchanged by the duplicate-tolerant read; it only decides which twin wins.
  */
 export declare function resolveLtAuthState(cookieString: string, stateCookieName?: string): LtAuthState | null;
+/**
+ * Clear the one-shot warning state.
+ *
+ * INTERNAL — test-only. Module-scope state survives every test in a file that
+ * does not call `vi.resetModules()`, which would make assertions on these
+ * warnings depend on test order. Production code must never call this.
+ */
+export declare function resetLtWarnOnceState(): void;
 /**
  * Determines if HTTP requests should use the Nuxt Vite dev proxy.
  *
@@ -124,6 +132,46 @@ export declare function resolveLtAuthState(cookieString: string, stateCookieName
  * @see https://github.com/lenneTech/nuxt-base-starter — Vite proxy configuration
  */
 export declare function isLocalDevApiProxy(): boolean;
+/**
+ * Outcome of resolving the API base URL for the current render scope.
+ *
+ * INTERNAL — plumbing for {@link buildLtApiUrl} and the `lt-config-check` plugin.
+ * Not part of the public API (absent from the package barrels and auto-imports);
+ * reachable only via a deep path import. Shape may change without a major bump.
+ */
+export interface LtApiUrlResolution {
+    /** Base URL to prefix onto API paths. `'/api'` in proxy mode, `''` when unresolved. */
+    baseUrl: string;
+    /** `true` when no API URL is configured for {@link scope}. */
+    missing: boolean;
+    /** `true` when the Vite dev proxy prefix is in use (see {@link isLocalDevApiProxy}). */
+    proxy: boolean;
+    /** The render scope the resolution was performed for. */
+    scope: 'client' | 'server';
+}
+/**
+ * Resolve the API base URL for the current render scope.
+ *
+ * INTERNAL — plumbing shared by {@link buildLtApiUrl} and the `lt-config-check`
+ * plugin; not part of the public API (absent from the barrels and auto-imports).
+ *
+ * Pure: it reads `runtimeConfig` and reports what it found, but never logs and
+ * never mutates. The `missing` flag lets callers decide how to surface the
+ * misconfiguration — {@link buildLtApiUrl} warns lazily, the `lt-config-check`
+ * plugin warns eagerly at app init. Both funnel through the same one-shot key,
+ * so the user sees exactly one warning either way.
+ *
+ * Throws when called outside a Nuxt runtime-config context; callers catch.
+ */
+export declare function resolveLtApiBaseUrl(): LtApiUrlResolution;
+/**
+ * Warn — at most once per module instance — that no API URL is configured.
+ *
+ * INTERNAL — shared by {@link buildLtApiUrl} and the `lt-config-check` plugin so
+ * an eager boot-time check and a lazy first-URL check never double-report. Not
+ * part of the public API (absent from the barrels and auto-imports).
+ */
+export declare function warnMissingLtApiUrl(scope: 'client' | 'server'): void;
 /**
  * Build a full API URL for a given path, handling SSR, proxy, and direct modes.
  *
@@ -157,6 +205,9 @@ export declare function isLocalDevApiProxy(): boolean;
  *
  * Trailing slashes on the base URL are automatically stripped.
  *
+ * A missing API URL is reported at most once per module instance — the condition
+ * is constant for the process, so repeating it per call only drowns other output.
+ *
  * @param path - The API path (e.g., `/system-setup/status`, `/i18n/errors/de`)
  */
 export declare function buildLtApiUrl(path: string): string;

package/dist/runtime/lib/auth-state.js

@@ -42,7 +42,17 @@ export function resolveLtAuthState(cookieString, stateCookieName) {
   }
   return fallback;
 }
-let _proxyFallbackWarned = false;
+const warnedKeys = /* @__PURE__ */ new Set();
+function warnOnce(key, message) {
+  if (warnedKeys.has(key)) {
+    return;
+  }
+  warnedKeys.add(key);
+  console.warn(message);
+}
+export function resetLtWarnOnceState() {
+  warnedKeys.clear();
+}
 export function isLocalDevApiProxy() {
   if (import.meta.server) {
     return false;
@@ -55,12 +65,10 @@ export function isLocalDevApiProxy() {
     }
     const buildId = runtimeConfig?.app && runtimeConfig.app?.buildId;
     if (buildId === "dev") {
-      if (!_proxyFallbackWarned) {
-        _proxyFallbackWarned = true;
-        console.warn(
-          "\n\u26A0\uFE0F  [LtExtensions] API proxy activated implicitly because nuxt dev was detected.\n    To make this explicit, add NUXT_PUBLIC_API_PROXY=true to your .env file.\n    If you do NOT want the proxy, set NUXT_PUBLIC_API_PROXY=false.\n"
-        );
-      }
+      warnOnce(
+        "api-proxy-fallback",
+        "\n\u26A0\uFE0F  [LtExtensions] API proxy activated implicitly because nuxt dev was detected.\n    To make this explicit, add NUXT_PUBLIC_API_PROXY=true to your .env file.\n    If you do NOT want the proxy, set NUXT_PUBLIC_API_PROXY=false.\n"
+      );
       return true;
     }
     return false;
@@ -68,26 +76,37 @@ export function isLocalDevApiProxy() {
     return false;
   }
 }
+const MISSING_API_URL_WARNING = {
+  client: "[LtExtensions] No API URL configured. Set NUXT_PUBLIC_API_URL. API paths stay relative and resolve against the app origin, so auth and setup calls 404 unless the app is served behind a same-origin reverse proxy.",
+  server: "[LtExtensions] No API URL configured for SSR. Set NUXT_API_URL or NUXT_PUBLIC_API_URL. API paths stay relative, so server-side requests never reach the backend: $fetch resolves them against Nitro (404) and global fetch rejects them as an invalid URL."
+};
+function stripTrailingSlashes(url) {
+  return url.replace(/\/+$/, "");
+}
+export function resolveLtApiBaseUrl() {
+  const runtimeConfig = useRuntimeConfig();
+  const publicUrl = runtimeConfig.public.apiUrl || "";
+  const authBaseURL = runtimeConfig.public?.ltExtensions?.auth?.baseURL || "";
+  if (import.meta.server) {
+    const apiUrl2 = runtimeConfig.apiUrl || publicUrl || authBaseURL;
+    return { baseUrl: stripTrailingSlashes(apiUrl2), missing: !apiUrl2, proxy: false, scope: "server" };
+  }
+  if (isLocalDevApiProxy()) {
+    return { baseUrl: "/api", missing: false, proxy: true, scope: "client" };
+  }
+  const apiUrl = publicUrl || authBaseURL;
+  return { baseUrl: stripTrailingSlashes(apiUrl), missing: !apiUrl, proxy: false, scope: "client" };
+}
+export function warnMissingLtApiUrl(scope) {
+  warnOnce(`missing-api-url:${scope}`, MISSING_API_URL_WARNING[scope]);
+}
 export function buildLtApiUrl(path) {
   try {
-    const runtimeConfig = useRuntimeConfig();
-    const publicUrl = runtimeConfig.public.apiUrl || "";
-    const authBaseURL = runtimeConfig.public?.ltExtensions?.auth?.baseURL || "";
-    if (import.meta.server) {
-      const apiUrl2 = runtimeConfig.apiUrl || publicUrl || authBaseURL;
-      if (!apiUrl2) {
-        console.warn("[LtExtensions] No API URL configured. Set NUXT_API_URL or NUXT_PUBLIC_API_URL.");
-      }
-      return `${(apiUrl2 || "").replace(/\/+$/, "")}${path}`;
-    }
-    if (isLocalDevApiProxy()) {
-      return `/api${path}`;
-    }
-    const apiUrl = publicUrl || authBaseURL;
-    if (!apiUrl) {
-      console.warn("[LtExtensions] No API URL configured. Set NUXT_PUBLIC_API_URL.");
+    const { baseUrl, missing, scope } = resolveLtApiBaseUrl();
+    if (missing) {
+      warnMissingLtApiUrl(scope);
     }
-    return `${(apiUrl || "").replace(/\/+$/, "")}${path}`;
+    return `${baseUrl}${path}`;
   } catch {
     return path;
   }

package/dist/runtime/plugins/lt-config-check.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Config Check Plugin
+ *
+ * Reports a missing API URL once at app init instead of waiting for whichever
+ * code path happens to build the first URL. The condition is read from
+ * `runtimeConfig` and is fixed for the module instance, so it belongs in a
+ * single boot-time check rather than in the hot `buildLtApiUrl()` path.
+ *
+ * Universal on purpose: SSR and the browser resolve the base URL from different
+ * keys (`NUXT_API_URL` vs `NUXT_PUBLIC_API_URL`) and can be misconfigured
+ * independently. On the server the plugin runs per request, but
+ * `warnMissingLtApiUrl()` is one-shot, so the warning still appears exactly once
+ * per process — and `buildLtApiUrl()` shares the same key, so it never repeats.
+ */
+import type { ObjectPlugin, Plugin } from '#app';
+declare const _default: ObjectPlugin & Plugin;
+export default _default;

package/dist/runtime/plugins/lt-config-check.js

@@ -0,0 +1,11 @@
+import { defineNuxtPlugin } from "#imports";
+import { resolveLtApiBaseUrl, warnMissingLtApiUrl } from "../lib/auth-state.js";
+export default defineNuxtPlugin(() => {
+  try {
+    const { missing, scope } = resolveLtApiBaseUrl();
+    if (missing) {
+      warnMissingLtApiUrl(scope);
+    }
+  } catch {
+  }
+});

package/dist/runtime/types/auth.d.ts

@@ -33,7 +33,7 @@ export interface LtAuthState {
  * All options have sensible defaults for nest-server compatibility
  */
 export interface LtAuthClientConfig {
-    /** API base URL (default: from env or http://localhost:3000) */
+    /** API base URL (default: `''` — empty means requests use the current app origin; production passes an explicit URL from `NUXT_PUBLIC_API_URL`. No implicit `localhost` fallback) */
     baseURL?: string;
     /** Auth API base path (default: '/iam' - must match nest-server betterAuth.basePath) */
     basePath?: string;

package/dist/runtime/types/module.d.ts

@@ -56,7 +56,7 @@ export interface LtAuthCookieNamesOptions {
 export interface LtAuthModuleOptions {
     /** Auth API base path (default: '/iam' - must match nest-server betterAuth.basePath) */
     basePath?: string;
-    /** API base URL (default: from env or http://localhost:3000) */
+    /** API base URL (default: `''` — resolved at runtime from `NUXT_PUBLIC_API_URL` / `NUXT_API_URL`; no implicit `localhost` fallback, so an unset URL keeps API paths relative to the app origin) */
     baseURL?: string;
     /** Override the cookie names used for auth state and JWT storage */
     cookieNames?: LtAuthCookieNamesOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nuxt-extensions",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "Reusable Nuxt 4 composables, components, and Better-Auth integration for lenne.tech projects",
   "repository": {
     "type": "git",