@uipkge/nuxt 0.1.14 → 0.1.16

package/README.md

@@ -8,7 +8,7 @@ Nuxt module for [i18now](https://i18now.com) — loads translations from the i18
 - Reloads translations on locale switch (client-side)
 - In development: detects missing translation keys and syncs them to i18now automatically
 - Suppresses vue-i18n missing-key warnings in dev — missing keys are expected until published
-- API key is never exposed to the browser (proxied through a local Nuxt server route)
+- API key is only present in development builds — never shipped to production
 - Zero bundle impact in production — dev-only code is tree-shaken at build time
 
 ## Installation
@@ -47,7 +47,7 @@ export default defineNuxtConfig({
 | Option        | Type       | Default                    | Description                                                                 |
 |---------------|------------|----------------------------|-----------------------------------------------------------------------------|
 | `projectId`   | `string`   | —                          | **Required.** Your i18now project ID.                                       |
-| `apiKey`      | `string`   | —                          | **Required.** Your i18now API key. Never sent to the browser.               |
+| `apiKey`      | `string`   | —                          | **Required.** Your i18now API key. Only used in dev builds.                 |
 | `host`        | `string`   | `https://i18now.com`       | i18now server URL. Set to `http://localhost:3220` for local development.    |
 | `cdnUrl`      | `string`   | `https://cdn.i18now.com`   | CDN base URL where published translations are served.                       |
 | `environment` | `string`   | `'dev'`                    | Which published environment to load translations from (`dev`, `stage`, `prod`). |
@@ -71,24 +71,24 @@ The server plugin fetches the published translation JSON from the CDN (`{cdnUrl}
 
 ### Development
 
-The client plugin intercepts every `$t()` and `useI18n().t()` call. When a key is missing from the CDN snapshot it batches that key (with its default value) and POSTs it to a local Nuxt server route (`/api/_i18now/sync`). The server route adds the API key and forwards the request to i18now — so your API key never appears in browser network requests.
+The client plugin intercepts every `$t()` and `useI18now().t()` call. When a key is missing from the CDN snapshot it batches that key (with its default value) and POSTs it directly to the i18now sync endpoint.
 
 ```
 Browser $t('key', 'Default text')
   → client plugin detects missing key
-  → POST /api/_i18now/sync  { keys: [{ key, value }] }
-  → Nuxt server adds apiKey
-  → POST i18now /api/v1/projects/:id/sync
+  → POST i18now /api/v1/projects/:id/sync  { apiKey, keys }
+  → i18now creates the key with source value
 ```
 
-The `useI18n` composable is auto-imported by the module and silently overrides the one from `@nuxtjs/i18n` — no changes to existing component code are required.
+The `useI18now` composable is auto-imported by the module. Use it in place of `useI18n` from vue-i18n — it adds sync detection on top of the standard `t()` function.
 
 Vue-i18n's missing-key and fallback warnings are suppressed automatically in dev. Keys are expected to be absent until they are published from the i18now dashboard, at which point they load from CDN and no longer trigger warnings.
 
 ## Security
 
-- `apiKey` is stored in Nuxt's private (server-only) `runtimeConfig` — it is never serialised into the client bundle or sent in any browser request.
+- `apiKey` is only included in `runtimeConfig.public` during **development** builds (`nuxt.options.dev`). In production, the API key is never serialised into the client bundle or `__NUXT__` payload.
 - The `syncIn` option defaults to `['development']`. **Never add `'production'` or `'staging'`** — doing so would expose your API key to end users and flood your project with traffic.
+- The client sync plugin is only registered in dev mode — it is completely absent from production builds.
 
 ## Local development against a local i18now server
 
@@ -104,12 +104,23 @@ i18now: {
 
 ## Playground
 
-A minimal playground is included in `playground/`. To run it:
+A minimal playground is included in `playground/`. It runs on **port 3227**.
 
 ```bash
 pnpm dev:playground
 ```
 
+### Framework playground ports
+
+All SDK playgrounds use fixed ports so they can run simultaneously alongside the i18now server (port 3220):
+
+| Package | Port |
+|---|---|
+| `@uipkge/react` | 3224 |
+| `@uipkge/vue` | 3225 |
+| `@uipkge/next` | 3226 |
+| `@uipkge/nuxt` | 3227 |
+
 ## Building locally
 
 ```bash

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=3.0.0"
   },
-  "version": "0.1.14",
+  "version": "0.1.16",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -21,8 +21,11 @@ const module$1 = defineNuxtModule({
     if (!options.apiKey) {
       console.warn("[i18now] apiKey is required. The module will not work until it is set.");
     }
+    if (options.cdnUrl && !options.cdnUrl.startsWith("http")) {
+      console.warn("[i18now] cdnUrl should be a valid HTTP(S) URL. Got: " + options.cdnUrl);
+    }
     const dangerousEnvs = (options.syncIn ?? []).filter(
-      (e) => ["production", "staging", "prod", "stage"].includes(e)
+      (e) => ["production", "staging", "prod", "stage"].includes(e.toLowerCase())
     );
     if (dangerousEnvs.length > 0) {
       console.error(
@@ -31,22 +34,33 @@ const module$1 = defineNuxtModule({
     }
     nuxt.options.runtimeConfig.public.i18now = {
       projectId: options.projectId,
-      apiKey: options.apiKey,
-      host: options.host,
       cdnUrl: options.cdnUrl,
       environment: options.environment,
-      syncIn: options.syncIn,
-      locale: options.locale
+      locale: options.locale,
+      // Dev-only fields — only included when the sync client plugin is active.
+      // In production builds these are undefined and the client plugin is not registered.
+      ...nuxt.options.dev ? {
+        apiKey: options.apiKey,
+        host: options.host,
+        syncIn: options.syncIn
+      } : {}
     };
     addPlugin({
       src: resolver.resolve("./runtime/plugin"),
       mode: "server"
     });
-    addImports({
-      name: "useI18now",
-      as: "useI18now",
-      from: resolver.resolve("./runtime/composables/useI18n")
-    });
+    addImports([
+      {
+        name: "useI18now",
+        as: "useI18now",
+        from: resolver.resolve("./runtime/composables/useI18n")
+      },
+      {
+        name: "useI18nowLocales",
+        as: "useI18nowLocales",
+        from: resolver.resolve("./runtime/composables/useI18nowLocales")
+      }
+    ]);
     if (nuxt.options.dev) {
       addPlugin({
         src: resolver.resolve("./runtime/plugin.client"),

package/dist/runtime/composables/useI18nowLocales.d.ts

@@ -0,0 +1,34 @@
+export interface I18nowLocale {
+    code: string;
+    name: string;
+    nativeName: string;
+    isSource: boolean;
+}
+/**
+ * Returns the list of locales published in the i18now dashboard.
+ *
+ * Fetches `{cdnUrl}/{projectId}/locales.json` (written on every publish)
+ * so the app auto-discovers new languages without code changes or redeployment.
+ *
+ * Usage:
+ * ```vue
+ * <script setup>
+ * const { locales, sourceLocale, pending } = useI18nowLocales()
+ * </script>
+ *
+ * <template>
+ *   <select @change="setLocale($event.target.value)">
+ *     <option v-for="l in locales" :key="l.code" :value="l.code">
+ *       {{ l.nativeName }}
+ *     </option>
+ *   </select>
+ * </template>
+ * ```
+ */
+export declare function useI18nowLocales(): {
+    locales: import("vue").ComputedRef<any>;
+    sourceLocale: import("vue").ComputedRef<any>;
+    pending: any;
+    error: any;
+    refresh: any;
+};

package/dist/runtime/composables/useI18nowLocales.js

@@ -0,0 +1,21 @@
+import { useAsyncData, useRuntimeConfig } from "#app";
+import { computed } from "vue";
+export function useI18nowLocales() {
+  const { projectId, cdnUrl } = useRuntimeConfig().public.i18now;
+  const { data, pending, error, refresh } = useAsyncData(
+    "i18now-locales",
+    async () => {
+      if (!projectId) return [];
+      const url = `${cdnUrl}/${projectId}/locales.json`;
+      const res = await fetch(url, { signal: AbortSignal.timeout(5e3) });
+      if (!res.ok) return [];
+      const data2 = await res.json();
+      if (!Array.isArray(data2)) return [];
+      return data2;
+    },
+    { default: () => [] }
+  );
+  const locales = computed(() => data.value ?? []);
+  const sourceLocale = computed(() => data.value?.find((l) => l.isSource) ?? null);
+  return { locales, sourceLocale, pending, error, refresh };
+}

package/dist/runtime/plugin.client.js

@@ -67,22 +67,43 @@ export default defineNuxtPlugin(async (nuxtApp) => {
     debug: import.meta.dev
   });
   const locale = i18nGlobal?.locale?.value ?? i18nGlobal?.locale ?? configLocale;
+  let loadLocaleController = null;
   async function loadLocale(targetLocale) {
+    if (loadLocaleController) loadLocaleController.abort();
+    loadLocaleController = new AbortController();
+    const { signal } = loadLocaleController;
     try {
       const url = `${cdnUrl}/${projectId}/publish/${environment}/${targetLocale}.json`;
-      const res = await fetch(url, { signal: AbortSignal.timeout(8e3) });
+      const timeout = setTimeout(() => loadLocaleController?.abort(), 5e3);
+      const res = await fetch(url, { signal });
+      clearTimeout(timeout);
       if (res.ok) {
         const data = await res.json();
+        if (typeof data !== "object" || data === null || Array.isArray(data)) {
+          if (import.meta.dev) {
+            console.warn(`[i18now] CDN response for locale '${targetLocale}' is not a valid object. Skipping.`);
+          }
+          syncer.setExistingKeys([]);
+          return;
+        }
         syncer.setExistingKeys(Object.keys(data));
         i18nGlobal?.setLocaleMessage(targetLocale, data);
-      } else if (import.meta.dev) {
-        console.warn(
-          `[i18now] Could not load translations from CDN (${res.status}). All keys will be sent to sync \u2014 this is safe, the backend deduplicates them. URL: ${url}`
-        );
+      } else {
+        syncer.setExistingKeys([]);
+        if (import.meta.dev) {
+          console.warn(
+            `[i18now] Could not load translations from CDN (${res.status}). All keys will be sent to sync \u2014 this is safe, the backend deduplicates them. URL: ${url}`
+          );
+        }
       }
     } catch (err) {
+      syncer.setExistingKeys([]);
       if (import.meta.dev) {
-        console.warn(`[i18now] CDN fetch failed for locale '${targetLocale}':`, err);
+        const isTimeout = err instanceof DOMException && err.name === "AbortError";
+        console.warn(
+          `[i18now] CDN fetch ${isTimeout ? "timed out" : "failed"} for locale '${targetLocale}'${isTimeout ? "" : ":"}`,
+          ...isTimeout ? [] : [err]
+        );
       }
     }
   }

package/dist/runtime/plugin.js

@@ -6,7 +6,7 @@ export default defineNuxtPlugin(async (nuxtApp) => {
   async function loadLocale(locale) {
     try {
       const url = `${cdnUrl}/${projectId}/publish/${environment}/${locale}.json`;
-      const res = await fetch(url, { signal: AbortSignal.timeout(8e3) });
+      const res = await fetch(url, { signal: AbortSignal.timeout(5e3) });
       if (!res.ok) {
         if (import.meta.dev) {
           console.warn(
@@ -15,7 +15,14 @@ export default defineNuxtPlugin(async (nuxtApp) => {
         }
         return;
       }
-      const messages = await res.json();
+      const data = await res.json();
+      if (typeof data !== "object" || data === null || Array.isArray(data)) {
+        if (import.meta.dev) {
+          console.warn(`[i18now] CDN response for locale '${locale}' is not a valid object. Skipping.`);
+        }
+        return;
+      }
+      const messages = data;
       if (i18n) i18n.setLocaleMessage(locale, messages);
     } catch (err) {
       if (import.meta.dev) {

package/dist/runtime/plugin.suppress-warnings.js

@@ -4,7 +4,7 @@ export default defineNuxtPlugin((nuxtApp) => {
   let symbolGlobal;
   if (!directGlobal) {
     const provides = nuxtApp.vueApp._context?.provides ?? {};
-    const i18nSym = Object.getOwnPropertySymbols(provides).find((s) => s.toString() === "Symbol(vue-i18n)");
+    const i18nSym = Object.getOwnPropertySymbols(provides).find((s) => s.toString().startsWith("Symbol(vue-i18n"));
     const i18nInstance = i18nSym ? provides[i18nSym] : void 0;
     symbolGlobal = i18nInstance?.global;
   }

package/package.json

@@ -1,27 +1,22 @@
 {
   "name": "@uipkge/nuxt",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "license": "MIT",
   "type": "module",
   "exports": {
     ".": {
+      "types": "./dist/module.d.mts",
       "import": "./dist/module.mjs"
     }
   },
   "main": "./dist/module.mjs",
+  "types": "./dist/module.d.mts",
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "nuxt-module-build build",
-    "dev": "nuxt-module-build prepare",
-    "dev:playground": "nuxi dev playground",
-    "prepack": "nuxt-module-build build",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "release": "vitest run && nuxt-module-build build && pnpm publish --access public --no-git-checks"
-  },
   "dependencies": {
     "@nuxt/kit": "^3.0.0"
   },
@@ -39,9 +34,18 @@
   },
   "devDependencies": {
     "@nuxt/module-builder": "^1.0.0",
-    "@uipkge/core": "workspace:*",
     "happy-dom": "^17.0.0",
     "nuxt": "^3.0.0",
-    "vitest": "^4.0.0"
+    "vitest": "^4.0.0",
+    "@uipkge/core": "0.1.1"
+  },
+  "scripts": {
+    "build": "nuxt-module-build build",
+    "dev": "nuxt-module-build prepare",
+    "dev:playground": "nuxi dev playground --port 3227",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "release": "vitest run && nuxt-module-build build && pnpm publish --access public --no-git-checks"
   }
-}
+}

package/dist/runtime/server/sync.d.ts

@@ -1,2 +0,0 @@
-declare const _default: (event: unknown) => unknown;
-export default _default;

package/dist/runtime/server/sync.js

@@ -1,48 +0,0 @@
-import { createError, defineEventHandler, readBody } from "h3";
-export default defineEventHandler(async (event) => {
-  const config = useRuntimeConfig(event);
-  const publicConfig = config.public?.i18now;
-  const env = process.env.NODE_ENV ?? "production";
-  if (!publicConfig?.syncIn?.includes(env)) {
-    throw createError({ statusCode: 403, statusMessage: "Key sync is disabled in this environment" });
-  }
-  if (!publicConfig.projectId || !publicConfig.host) {
-    throw createError({ statusCode: 500, statusMessage: "i18now module is not configured" });
-  }
-  const privateConfig = config.i18now;
-  const apiKey = privateConfig?.apiKey;
-  if (!apiKey) {
-    throw createError({ statusCode: 500, statusMessage: "i18now apiKey is not configured" });
-  }
-  let body;
-  try {
-    body = await readBody(event);
-  } catch {
-    throw createError({ statusCode: 400, statusMessage: "Invalid request body" });
-  }
-  if (!Array.isArray(body?.keys)) {
-    throw createError({ statusCode: 400, statusMessage: 'Request body must contain a "keys" array' });
-  }
-  const validKeys = body.keys.filter(
-    (item) => item !== null && typeof item === "object" && typeof item.key === "string" && item.key.length > 0 && typeof item.value === "string" && item.value.length > 0
-  );
-  if (validKeys.length === 0) {
-    return { synced: 0 };
-  }
-  if (validKeys.length > 100) {
-    throw createError({ statusCode: 400, statusMessage: "Maximum 100 keys per request" });
-  }
-  const res = await fetch(
-    `${publicConfig.host}/api/v1/projects/${publicConfig.projectId}/sync`,
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ apiKey, keys: validKeys })
-    }
-  );
-  const data = await res.json();
-  if (!res.ok) {
-    throw createError({ statusCode: res.status, data });
-  }
-  return data;
-});