1.5.0: refactor API URL resolution to runtime-only config, add cookie Secure flag, and update deps

Author: kaihaase

README.md

@@ -42,6 +42,58 @@ npm install tus-js-client
 - **i18n Support** - English and German translations (works without i18n too)
 - **Auto-imports** - All composables and components are auto-imported
 
+## Environment Variables
+
+| Variable | Context | Description |
+|----------|---------|-------------|
+| `NUXT_PUBLIC_API_URL` | Client + Server | Public API URL. Primary way to configure the API endpoint. Used for client-side requests and as SSR fallback. |
+| `NUXT_API_URL` | Server only | Internal API URL for SSR requests. Use when the backend has a private network address that should not be exposed to the client. |
+| `NUXT_PUBLIC_API_PROXY` | Client | Set to `true` to enable the Vite dev proxy. Routes client requests through `/api/` for same-origin cookies. **Only for local development.** |
+
+### How URL Resolution Works
+
+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`
+
+**Client fallback chain (no proxy):**
+`NUXT_PUBLIC_API_URL` → `auth.baseURL` (from nuxt.config.ts) → `http://localhost:3000`
+
+**Client with proxy (`NUXT_PUBLIC_API_PROXY=true`):**
+All requests go to `/api/{path}` — the Vite dev proxy forwards them to the backend.
+
+> **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
+
+**Local development** — Frontend and backend on different ports, proxy ensures same-origin cookies:
+```bash
+NUXT_PUBLIC_API_URL=http://localhost:3000
+NUXT_PUBLIC_API_PROXY=true
+```
+
+**Production (simple)** — Backend reachable via public URL from both SSR and client:
+```bash
+NUXT_PUBLIC_API_URL=https://api.example.com
+```
+
+**Production (internal network)** — SSR uses fast internal route, client uses public URL:
+```bash
+NUXT_PUBLIC_API_URL=https://api.example.com
+NUXT_API_URL=http://api-internal:3000
+```
+
+**Legacy (nuxt.config.ts only)** — Works but env vars are preferred for runtime flexibility:
+```typescript
+// nuxt.config.ts
+ltExtensions: {
+  auth: {
+    baseURL: 'https://api.example.com',
+  },
+}
+```
+
 ## Configuration
 
 ```typescript
@@ -53,7 +105,7 @@ export default defineNuxtConfig({
     // Auth configuration
     auth: {
       enabled: true,                // Enable auth features
-      baseURL: '',                  // API base URL (empty = use Nuxt proxy)
+      baseURL: '',                  // API base URL (empty = use env vars)
       basePath: '/iam',             // Better-Auth endpoint prefix
       loginPath: '/auth/login',     // Login redirect path
       twoFactorRedirectPath: '/auth/2fa',  // 2FA redirect path
@@ -68,6 +120,18 @@ export default defineNuxtConfig({
         enabled: true,              // 401 auto-handler
         publicPaths: ['/auth/login', '/auth/register'],
       },
+
+      // System setup (first admin user creation)
+      systemSetup: {
+        enabled: false,             // Enable setup flow
+        setupPath: '/auth/setup',   // Setup page path
+      },
+    },
+
+    // Error translation configuration
+    errorTranslation: {
+      enabled: true,                // Translate backend error codes
+      defaultLocale: 'de',          // Fallback locale
     },
 
     // TUS upload configuration
@@ -298,9 +362,12 @@ The package works **with or without** `@nuxtjs/i18n`:
 | Composable | Description |
 |------------|-------------|
 | `useLtAuth()` | Better-Auth integration with session, passkey, 2FA |
+| `useLtAuthClient()` | Direct access to the Better-Auth client singleton |
+| `useLtErrorTranslation()` | Translate backend error codes to user-friendly messages |
 | `useLtTusUpload()` | TUS protocol file uploads with pause/resume |
 | `useLtFile()` | File utilities (size formatting, URLs) |
 | `useLtShare()` | Web Share API with clipboard fallback |
+| `useSystemSetup()` | System setup flow for initial admin user creation |
 
 ### Components
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nuxt-extensions",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Reusable Nuxt 4 composables, components, and Better-Auth integration for lenne.tech projects",
   "repository": {
     "type": "git",
@@ -12,7 +12,7 @@
   },
   "author": "lenne.Tech <info@lenne.tech> (https://lenne.tech)",
   "license": "MIT",
-  "packageManager": "pnpm@10.29.2",
+  "packageManager": "pnpm@10.32.1",
   "type": "module",
   "exports": {
     ".": {
@@ -69,7 +69,7 @@
     "release": "pnpm format:check && pnpm lint && pnpm test:types && pnpm test && pnpm prepack"
   },
   "dependencies": {
-    "@nuxt/kit": "4.3.0"
+    "@nuxt/kit": "4.4.2"
   },
   "peerDependencies": {
     "@better-auth/passkey": ">=1.0.0",
@@ -93,30 +93,37 @@
     }
   },
   "devDependencies": {
-    "@better-auth/passkey": "1.4.18",
-    "@nuxt/devtools": "3.1.1",
-    "@playwright/test": "1.58.1",
+    "@better-auth/passkey": "1.5.5",
+    "@nuxt/devtools": "3.2.3",
     "@nuxt/module-builder": "1.0.2",
-    "@nuxt/schema": "4.3.0",
-    "@nuxt/test-utils": "3.23.0",
-    "@types/node": "25.2.0",
-    "@vitest/coverage-v8": "4.0.18",
-    "@vue/test-utils": "2.4.6",
-    "better-auth": "1.4.18",
-    "happy-dom": "20.5.0",
-    "nuxt": "4.3.0",
-    "oxfmt": "0.28.0",
-    "oxlint": "1.43.0",
+    "@nuxt/schema": "4.4.2",
+    "@playwright/test": "1.58.2",
+    "@types/node": "25.5.0",
+    "@vitest/coverage-v8": "4.1.0",
+    "better-auth": "1.5.5",
+    "happy-dom": "20.8.4",
+    "nuxt": "4.4.2",
+    "oxfmt": "0.40.0",
+    "oxlint": "1.55.0",
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
-    "vitest": "4.0.18",
-    "vue-tsc": "3.2.4"
+    "vitest": "4.1.0",
+    "vue-tsc": "3.2.5"
   },
   "pnpm": {
     "onlyBuiltDependencies": [
       "@parcel/watcher",
       "esbuild"
-    ]
+    ],
+    "overrides": {
+      "minimatch@>=5.0.0 <5.1.8": "5.1.8",
+      "minimatch@>=9.0.0 <9.0.7": "9.0.7",
+      "minimatch@>=10.0.0 <10.2.3": "10.2.3",
+      "rollup@>=4.0.0 <4.59.0": ">=4.59.0",
+      "serialize-javascript@<=7.0.2": ">=7.0.3",
+      "svgo@=4.0.0": ">=4.0.1",
+      "tar@<7.5.11": "7.5.11"
+    }
   },
   "keywords": [
     "nuxt",