@uipkge/nuxt 0.1.0

package/README.md

@@ -0,0 +1,130 @@
+# @uipkge/nuxt
+
+Nuxt module for [i18now](https://i18now.com) — loads translations from the i18now CDN and automatically syncs new keys to your project during development.
+
+## Features
+
+- Loads published translations from the i18now CDN at SSR time
+- 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)
+- Zero bundle impact in production — dev-only code is tree-shaken at build time
+
+## Installation
+
+```bash
+npm install @uipkge/nuxt
+# or
+pnpm add @uipkge/nuxt
+```
+
+`@nuxtjs/i18n` is a dependency and will be installed automatically.
+
+## Setup
+
+Add the module to `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@uipkge/nuxt'],
+
+  i18now: {
+    projectId: process.env.I18NOW_PROJECT_ID ?? '',
+    apiKey: process.env.I18NOW_API_KEY ?? '',
+  },
+
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en', 'es', 'fr'],
+    bundle: {
+      optimizeTranslationDirective: false, // buggy, deprecated in v10
+    },
+  },
+})
+```
+
+## Configuration
+
+| Option        | Type       | Default                    | Description                                                                 |
+|---------------|------------|----------------------------|-----------------------------------------------------------------------------|
+| `projectId`   | `string`   | —                          | **Required.** Your i18now project ID.                                       |
+| `apiKey`      | `string`   | —                          | **Required.** Your i18now API key. Never sent to the browser.               |
+| `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`). |
+| `syncIn`      | `string[]` | `['development']`          | Node environments where missing-key sync is active. Keep as `['development']`. |
+| `locale`      | `string`   | `'en'`                     | Fallback locale used before `@nuxtjs/i18n` initialises.                     |
+
+### Environment variables
+
+Store secrets in `.env`:
+
+```env
+I18NOW_PROJECT_ID=your-project-id
+I18NOW_API_KEY=your-api-key
+```
+
+## How it works
+
+### Production
+
+The server plugin fetches the published translation JSON from the CDN (`{cdnUrl}/{projectId}/publish/{environment}/{locale}.json`) during SSR and injects it into vue-i18n. Translations are refreshed on locale switch.
+
+### 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.
+
+```
+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
+```
+
+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.
+
+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.
+- 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.
+
+## Local development against a local i18now server
+
+```ts
+// nuxt.config.ts
+i18now: {
+  projectId: 'your-project-id',
+  apiKey: 'your-api-key',
+  host: 'http://localhost:3220',
+  cdnUrl: 'http://localhost:3220', // if serving snapshots locally
+  environment: 'dev',
+},
+```
+
+## Playground
+
+A minimal playground is included in `playground/`. To run it:
+
+```bash
+pnpm dev:playground
+```
+
+## Building locally
+
+```bash
+pnpm build
+```
+
+To use the built package in another local project, add a `file:` reference:
+
+```json
+{
+  "dependencies": {
+    "@uipkge/nuxt": "file:../path/to/i18now/packages/nuxt"
+  }
+}
+```

package/dist/module.d.mts

@@ -0,0 +1,22 @@
+import * as nuxt_schema from 'nuxt/schema';
+
+interface ModuleOptions {
+    projectId: string;
+    apiKey: string;
+    host?: string;
+    /** CDN base URL where published translations are served. Default: https://cdn.i18now.com */
+    cdnUrl?: string;
+    /** Which published environment to load translations from. Default: 'dev' */
+    environment?: string;
+    /** Environments where key sync is active. Default: ['development'] */
+    syncIn?: string[];
+    /**
+     * Fallback locale to load from CDN when @nuxtjs/i18n has not yet initialised.
+     * Default: 'en'
+     */
+    locale?: string;
+}
+declare const _default: nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "@uipkge/nuxt",
+  "configKey": "i18now",
+  "compatibility": {
+    "nuxt": ">=3.0.0"
+  },
+  "version": "0.1.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,75 @@
+import { defineNuxtModule, createResolver, addPlugin, addServerHandler, addImports } from '@nuxt/kit';
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "@uipkge/nuxt",
+    configKey: "i18now",
+    compatibility: { nuxt: ">=3.0.0" }
+  },
+  // Auto-install @nuxtjs/i18n when the user hasn't added it themselves.
+  // It ships as a dependency of @uipkge/nuxt so no separate install is needed.
+  moduleDependencies: {
+    "@nuxtjs/i18n": { version: "^9.0.0" }
+  },
+  defaults: {
+    host: "https://i18now.com",
+    cdnUrl: "https://cdn.i18now.com",
+    environment: "dev",
+    syncIn: ["development"],
+    locale: "en"
+  },
+  async setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    if (!options.projectId) {
+      console.warn("[i18now] projectId is required. The module will not work until it is set.");
+    }
+    if (!options.apiKey) {
+      console.warn("[i18now] apiKey is required. The module will not work until it is set.");
+    }
+    const dangerousEnvs = (options.syncIn ?? []).filter(
+      (e) => ["production", "staging", "prod", "stage"].includes(e)
+    );
+    if (dangerousEnvs.length > 0) {
+      console.error(
+        `[i18now] DANGER: syncIn includes "${dangerousEnvs.join('", "')}" \u2014 key sync is enabled in a production-like environment. This will expose your API key to users and flood i18now with production traffic. syncIn should only contain "development".`
+      );
+    }
+    nuxt.options.runtimeConfig.i18now = {
+      apiKey: options.apiKey
+    };
+    nuxt.options.runtimeConfig.public.i18now = {
+      projectId: options.projectId,
+      host: options.host,
+      cdnUrl: options.cdnUrl,
+      environment: options.environment,
+      syncIn: options.syncIn,
+      locale: options.locale
+    };
+    addPlugin({
+      src: resolver.resolve("./runtime/plugin"),
+      mode: "server"
+    });
+    if (nuxt.options.dev) {
+      addServerHandler({
+        route: "/api/_i18now/sync",
+        handler: resolver.resolve("./runtime/server/sync"),
+        method: "post"
+      });
+      addPlugin({
+        src: resolver.resolve("./runtime/plugin.client"),
+        mode: "client"
+      });
+      addPlugin({
+        src: resolver.resolve("./runtime/plugin.suppress-warnings")
+      });
+      addImports({
+        name: "useI18n",
+        as: "useI18n",
+        from: resolver.resolve("./runtime/composables/useI18n"),
+        priority: 2
+      });
+    }
+  }
+});
+
+export { module$1 as default };

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

@@ -0,0 +1,11 @@
+import { useI18n as _useI18n } from 'vue-i18n';
+type UseI18nOptions = Parameters<typeof _useI18n>[0];
+type UseI18nReturn = ReturnType<typeof _useI18n>;
+/**
+ * Drop-in replacement for useI18n() that wraps t() to sync missing keys to i18now.
+ * Auto-imported by the @uipkge/nuxt module — no code changes required.
+ */
+export declare function useI18n(options?: UseI18nOptions): UseI18nReturn & {
+    te: (key: string, locale?: string) => boolean;
+};
+export {};

package/dist/runtime/composables/useI18n.js

@@ -0,0 +1,24 @@
+import { useNuxtApp } from "#app";
+import { useI18n as _useI18n } from "vue-i18n";
+export function useI18n(options) {
+  const i18n = _useI18n({ useScope: "global", ...options });
+  const nuxtApp = useNuxtApp();
+  const originalT = i18n.t.bind(i18n);
+  const patchedT = (key, defaultValue, ...rest) => {
+    const result = originalT(key, defaultValue, ...rest);
+    const sync = nuxtApp.$i18nowSync;
+    if (sync && !sync.existingKeys.has(key) && typeof defaultValue === "string") {
+      sync.syncKey(key, defaultValue);
+    }
+    return result;
+  };
+  const te = (key, _locale) => {
+    const result = originalT(key);
+    return typeof result === "string" && result !== key;
+  };
+  return {
+    ...i18n,
+    te,
+    t: patchedT
+  };
+}

package/dist/runtime/plugin.client.d.ts

@@ -0,0 +1,9 @@
+declare const _default: (nuxtApp: unknown) => Promise<{
+    provide: {
+        i18nowSync: {
+            syncKey: (key: string, value: string) => void;
+            existingKeys: Set<string>;
+        };
+    };
+} | undefined>;
+export default _default;

package/dist/runtime/plugin.client.js

@@ -0,0 +1,93 @@
+import { defineNuxtPlugin, useRuntimeConfig } from "#app";
+const MAX_TRACKED = 2e3;
+const MAX_RETRIES = 3;
+export default defineNuxtPlugin(async (nuxtApp) => {
+  const { projectId, cdnUrl, environment, syncIn, locale: configLocale } = useRuntimeConfig().public.i18now;
+  if (!syncIn.includes(process.env.NODE_ENV ?? "development")) return;
+  if (!projectId) {
+    console.warn("[i18now] projectId is not set \u2014 key sync disabled.");
+    return;
+  }
+  const i18nGlobal = nuxtApp.$i18n ?? nuxtApp.vueApp.config.globalProperties.$i18n;
+  const existingKeys = /* @__PURE__ */ new Set();
+  const locale = i18nGlobal?.locale?.value ?? i18nGlobal?.locale ?? configLocale;
+  async function loadLocale(targetLocale) {
+    try {
+      const res = await fetch(`${cdnUrl}/${projectId}/publish/${environment}/${targetLocale}.json`);
+      if (res.ok) {
+        const data = await res.json();
+        existingKeys.clear();
+        for (const key of Object.keys(data)) existingKeys.add(key);
+        i18nGlobal?.setLocaleMessage(targetLocale, data);
+      } else if (process.env.NODE_ENV === "development") {
+        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: ${cdnUrl}/${projectId}/publish/${environment}/${targetLocale}.json`
+        );
+      }
+    } catch (err) {
+      if (process.env.NODE_ENV === "development") {
+        console.warn(`[i18now] CDN fetch failed for locale '${targetLocale}':`, err);
+      }
+    }
+  }
+  await loadLocale(locale);
+  const synced = /* @__PURE__ */ new Set();
+  const retries = /* @__PURE__ */ new Map();
+  const pending = /* @__PURE__ */ new Map();
+  let flushTimer = null;
+  function flush() {
+    flushTimer = null;
+    if (pending.size === 0) return;
+    const keys = Array.from(pending.entries()).map(([key, value]) => ({ key, value }));
+    pending.clear();
+    fetch("/api/_i18now/sync", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ keys })
+    }).then((res) => {
+      if (!res.ok) {
+        if (process.env.NODE_ENV === "development") {
+          res.json().then((data) => console.warn(`[i18now] Sync failed (${res.status}):`, data?.statusMessage ?? data)).catch(() => console.warn(`[i18now] Sync failed with status ${res.status}`));
+        }
+        throw new Error(`${res.status}`);
+      }
+    }).catch(() => {
+      for (const { key } of keys) {
+        const attempts = (retries.get(key) ?? 0) + 1;
+        if (attempts < MAX_RETRIES) {
+          retries.set(key, attempts);
+          synced.delete(key);
+        } else {
+          retries.delete(key);
+          if (process.env.NODE_ENV === "development") {
+            console.warn(`[i18now] Sync failed after ${MAX_RETRIES} attempts for key "${key}". Giving up.`);
+          }
+        }
+      }
+    });
+  }
+  function syncKey(key, value) {
+    if (synced.has(key) || synced.size >= MAX_TRACKED) return;
+    synced.add(key);
+    pending.set(key, value);
+    if (!flushTimer) flushTimer = setTimeout(flush, 0);
+  }
+  const originalGlobalT = nuxtApp.vueApp.config.globalProperties.$t;
+  if (originalGlobalT) {
+    nuxtApp.vueApp.config.globalProperties.$t = function(key, defaultValue, ...rest) {
+      const result = originalGlobalT.call(this, key, defaultValue, ...rest);
+      if (!existingKeys.has(key) && typeof defaultValue === "string") {
+        syncKey(key, defaultValue);
+      }
+      return result;
+    };
+  }
+  nuxtApp.hook("i18n:beforeLocaleSwitch", async ({ newLocale }) => {
+    await loadLocale(newLocale);
+  });
+  return {
+    provide: {
+      i18nowSync: { syncKey, existingKeys }
+    }
+  };
+});

package/dist/runtime/plugin.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (nuxtApp: unknown) => Promise<void>;
+export default _default;

package/dist/runtime/plugin.js

@@ -0,0 +1,23 @@
+import { defineNuxtPlugin, useRuntimeConfig } from "#app";
+export default defineNuxtPlugin(async (nuxtApp) => {
+  const { projectId, cdnUrl, environment, locale: configLocale } = useRuntimeConfig().public.i18now;
+  const i18n = nuxtApp.$i18n ?? nuxtApp.vueApp.config.globalProperties.$i18n;
+  async function loadLocale(locale) {
+    try {
+      const url = `${cdnUrl}/${projectId}/publish/${environment}/${locale}.json`;
+      const res = await fetch(url);
+      if (!res.ok) return;
+      const messages = await res.json();
+      if (i18n) i18n.setLocaleMessage(locale, messages);
+    } catch (err) {
+      if (process.env.NODE_ENV === "development") {
+        console.warn(`[i18now] Failed to load locale '${locale}' from CDN:`, err);
+      }
+    }
+  }
+  const currentLocale = i18n?.locale?.value ?? i18n?.locale ?? configLocale;
+  await loadLocale(currentLocale);
+  nuxtApp.hook("i18n:beforeLocaleSwitch", async ({ newLocale }) => {
+    await loadLocale(newLocale);
+  });
+});

package/dist/runtime/plugin.suppress-warnings.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Dev-only: suppress vue-i18n "Not found key" and fallback warnings.
+ * In i18now's workflow, missing keys are expected — they haven't been published
+ * to the CDN yet. The sync plugin handles them automatically, so the warnings
+ * are noise rather than actionable signal.
+ *
+ * Note: In @nuxtjs/i18n v9, nuxtApp.$i18n is the NuxtI18n object (with setLocale,
+ * locales, etc.) — it has no .global property. The real vue-i18n I18n instance
+ * lives under Symbol('vue-i18n') in the Vue app's provides.
+ */
+declare const _default: (nuxtApp: unknown) => void;
+export default _default;

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

@@ -0,0 +1,11 @@
+import { defineNuxtPlugin } from "#app";
+export default defineNuxtPlugin((nuxtApp) => {
+  const provides = nuxtApp.vueApp._context?.provides ?? {};
+  const i18nSym = Object.getOwnPropertySymbols(provides).find((s) => s.toString() === "Symbol(vue-i18n)");
+  const i18nInstance = i18nSym ? provides[i18nSym] : void 0;
+  const global = i18nInstance?.global;
+  if (global) {
+    global.missingWarn = false;
+    global.fallbackWarn = false;
+  }
+});

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

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

package/dist/runtime/server/sync.js

@@ -0,0 +1,42 @@
+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 ?? "development";
+  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' });
+  }
+  if (body.keys.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: body.keys })
+    }
+  );
+  const data = await res.json();
+  if (!res.ok) {
+    throw createError({ statusCode: res.status, data });
+  }
+  return data;
+});

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@uipkge/nuxt",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "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"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^3.0.0",
+    "@nuxtjs/i18n": "^9.0.0"
+  },
+  "peerDependencies": {
+    "vue-i18n": "^9.0.0 || ^10.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vue-i18n": { "optional": true }
+  },
+  "devDependencies": {
+    "@nuxt/module-builder": "^1.0.0",
+    "happy-dom": "^17.0.0",
+    "nuxt": "^3.0.0",
+    "vitest": "^4.0.0"
+  }
+}