@merkaly/nuxt 0.10.5 → 0.11.0

package/README.md

@@ -75,6 +75,51 @@ The sitemap is only installed for indexable apps and is served at `/sitemap.xml`
 alternate points to `merkaly.i18n.defaultLocale`; the sitemap is installed after
 `@nuxtjs/i18n` so it reads those options.
 
+## PostHog
+
+Product analytics with [PostHog](https://posthog.com), **US region**, behind a
+first-party proxy. Set the project key and the module does the rest:
+
+```ts
+export default defineNuxtConfig({
+  merkaly: {
+    posthog: process.env.POSTHOG_KEY, // phc_...
+  },
+});
+```
+
+Without a key nothing is installed: no plugin, no proxy route and no
+`posthog-js` in the bundle. With a key it lands in
+`runtimeConfig.public.merkaly.posthog`, so `NUXT_PUBLIC_MERKALY_POSTHOG`
+overrides it at runtime.
+
+**Client plugin.** Initializes `posthog-js` **only in production builds**
+(`nuxt dev` never sends events) with `api_host: '/phog'` and
+`ui_host: 'https://us.posthog.com'`. It identifies the Auth0 user from
+`useAuth()` (`identify(sub, { email, name })`) and calls `posthog.reset()` on
+logout. The app can keep using `import posthog from 'posthog-js'` for
+`capture()`: the module dedupes `posthog-js` so the app and the plugin share
+the initialized instance (keep `posthog-js` as an app dependency).
+
+**Proxy `/phog/**`.** A Nitro server route, so apps must run as a Node server
+(`node .output/server`), not as static files.
+
+| Path | Upstream |
+|---|---|
+| `/phog/static/*`, `/phog/array/*` | `https://us-assets.i.posthog.com` |
+| everything else (`/e/`, `/batch/`, `/s/`, `/i/v1/*`, `/flags/`, `/decide/`...) | `https://us.i.posthog.com` |
+
+- Path and query string are kept; `Host` is the upstream host (PostHog answers 401 otherwise).
+- Forwarded: `PostHog-*` headers, `Content-Type`, `Content-Encoding`, `User-Agent`, `Accept`, and `Authorization` only when it is a PostHog token (`Bearer phc_`, `phs_` or `phx_`).
+- `X-Forwarded-For` gets the client IP appended, so PostHog geolocates the visitor and not the server.
+- **Cookies are never forwarded**, and PostHog `Set-Cookie` headers never reach the app domain.
+- The request body is streamed, up to **64 MB** (session recordings); larger bodies get `413`.
+- The response is streamed back with its status and cache headers.
+
+The path is `/phog` because ad blockers drop requests to paths such as
+`/posthog`, `/analytics`, `/tracking` or `/telemetry`; a first-party, neutral
+path keeps events flowing.
+
 ## Money formatting
 
 Money in Merkaly is stored as **integer cents**. `MKFormatMoney`, `MKInputMoney`,

package/dist/module.d.mts

@@ -52,6 +52,8 @@ interface MerkalyModuleOptions {
         domain: string;
         localhost: string;
     };
+    /** PostHog project key (`phc_...`, US region). Empty installs nothing. */
+    posthog?: string;
     sentry: {
         dsn: string;
         project: string;

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=3.14.0"
   },
-  "version": "0.10.5",
+  "version": "0.11.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -38,6 +38,7 @@ const defaultOptions = {
     domain: "",
     localhost: ""
   },
+  posthog: "",
   sentry: {
     dsn: "",
     project: "",
@@ -59,6 +60,9 @@ function hasI18nConfig(options) {
 function hasPlausibleConfig(options) {
   return Boolean(options.plausible?.domain);
 }
+function hasPosthogConfig(options) {
+  return Boolean(options.posthog);
+}
 function hasSentryBuildConfig(options) {
   return Boolean(options.sentry.project && options.sentry.token);
 }
@@ -189,6 +193,8 @@ function configureRuntimeConfig(nuxt, options) {
       i18n: options.i18n,
       money: options.money,
       plausible: options.plausible,
+      posthog: options.posthog,
+      // NUXT_PUBLIC_MERKALY_POSTHOG overrides it at runtime
       sentry: {
         dsn: options.sentry.dsn,
         project: options.sentry.project
@@ -247,14 +253,15 @@ function configureFontAwesome(nuxt) {
     src: FONT_AWESOME_KIT_URL
   });
 }
-function configureVite(nuxt) {
+function configureVite(nuxt, options) {
   nuxt.options.vite = defu(nuxt.options.vite || {}, {
     plugins: [svgLoader()],
     // Force a single shared notivue instance so consumers don't have to declare
     // `vite.resolve.dedupe: ['notivue']` themselves (avoids the duplicate-instance
     // `useNotivueInstance()` error, especially when @merkaly/nuxt is linked locally).
     resolve: {
-      dedupe: ["notivue"]
+      dedupe: ["notivue", ...hasPosthogConfig(options) ? ["posthog-js"] : []]
+      // app imports share the initialized posthog
     }
   });
 }
@@ -266,16 +273,26 @@ function configureNuxtOptions(nuxt, options) {
     configureSentry(nuxt, options);
   }
   configureFontAwesome(nuxt);
-  configureVite(nuxt);
+  configureVite(nuxt, options);
 }
 function registerRuntimeFeatures(options, resolver) {
   addPlugin({ src: resolver.resolve("./runtime/plugins/api.global") });
   addPlugin({ src: resolver.resolve("./runtime/plugins/auth0.client") });
   addPlugin({ src: resolver.resolve("./runtime/plugins/sentry.global") });
+  if (hasPosthogConfig(options)) {
+    addPlugin({ src: resolver.resolve("./runtime/plugins/posthog.client") });
+  }
   addServerHandler({
     handler: resolver.resolve("./runtime/server/middleware/proxy"),
     middleware: true
   });
+  if (hasPosthogConfig(options)) {
+    addServerHandler({
+      handler: resolver.resolve("./runtime/server/routes/posthog"),
+      route: "/phog/**"
+      // neutral name, ad blockers match /posthog and /analytics
+    });
+  }
   addRouteMiddleware({
     global: options.auth0.requiresAuth,
     name: "auth",
@@ -329,6 +346,9 @@ const module$1 = defineNuxtModule({
     configureNuxtOptions(nuxt, options);
     await configureExternalIntegrations(nuxt, logger);
     registerRuntimeFeatures(options, resolver);
+    if (hasPosthogConfig(options)) {
+      logger.info("Loaded PostHog (proxy /phog)");
+    }
   }
 });
 

package/dist/runtime/plugins/posthog.client.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/plugins/posthog.client.js

@@ -0,0 +1,22 @@
+import posthog from "posthog-js";
+import { watchImmediate } from "@vueuse/core";
+import { defineNuxtPlugin, useRuntimeConfig } from "#app";
+import { useAuth } from "../composables/useAuth.js";
+export default defineNuxtPlugin(() => {
+  if (import.meta.dev) return;
+  const { public: $config } = useRuntimeConfig();
+  if (!$config.merkaly.posthog) {
+    console.warn("[posthog] merkaly.posthog is empty, analytics disabled");
+    return;
+  }
+  posthog.init($config.merkaly.posthog, {
+    api_host: "/phog",
+    // first-party proxy
+    ui_host: "https://us.posthog.com"
+  });
+  const { user } = useAuth();
+  watchImmediate(() => user.value?.sub, (sub, previous) => {
+    if (sub) return posthog.identify(sub, { email: user.value?.email, name: user.value?.name });
+    if (previous) posthog.reset();
+  });
+});

package/dist/runtime/server/routes/posthog.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/routes/posthog.js

@@ -0,0 +1,61 @@
+import { createError, defineEventHandler, getRequestHeader, getRequestWebStream, send, sendStream, setResponseHeaders, setResponseStatus } from "h3";
+const PROXY_PREFIX = "/phog";
+const INGEST_ORIGIN = "https://us.i.posthog.com";
+const ASSETS_ORIGIN = "https://us-assets.i.posthog.com";
+const ASSETS_PATH_PATTERN = /^\/(static|array)\//;
+const POSTHOG_TOKEN_PATTERN = /^Bearer ph[csx]_/;
+const MAX_BODY_BYTES = 64 * 1024 * 1024;
+const REQUEST_HEADERS = ["accept", "content-encoding", "content-type", "user-agent"];
+const RESPONSE_HEADERS = ["cache-control", "content-type", "etag", "expires", "last-modified", "location", "retry-after", "vary"];
+function resolveTarget(event) {
+  const path = event.path.slice(PROXY_PREFIX.length) || "/";
+  const origin = ASSETS_PATH_PATTERN.test(path) ? ASSETS_ORIGIN : INGEST_ORIGIN;
+  return new URL(path, origin);
+}
+function buildHeaders(event, target) {
+  const incoming = event.node.req.headers;
+  const headers = new Headers({ host: target.host });
+  Object.keys(incoming).filter((name) => name.startsWith("posthog-") || REQUEST_HEADERS.includes(name)).forEach((name) => headers.set(name, String(incoming[name])));
+  const authorization = getRequestHeader(event, "authorization");
+  if (authorization && POSTHOG_TOKEN_PATTERN.test(authorization)) headers.set("authorization", authorization);
+  const chain = getRequestHeader(event, "x-forwarded-for");
+  const client = event.node.req.socket.remoteAddress;
+  headers.set("x-forwarded-for", [chain, client].filter(Boolean).join(", "));
+  return headers;
+}
+function limitBody(event, state) {
+  const stream = getRequestWebStream(event);
+  if (!stream) return void 0;
+  let size = 0;
+  return stream.pipeThrough(new TransformStream({
+    transform(chunk, controller) {
+      size += chunk.byteLength;
+      if (size <= MAX_BODY_BYTES) return controller.enqueue(chunk);
+      state.tooLarge = true;
+      controller.error(new Error("PostHog body too large"));
+    }
+  }));
+}
+export default defineEventHandler((event) => {
+  if (Number(getRequestHeader(event, "content-length")) > MAX_BODY_BYTES) {
+    throw createError({ statusCode: 413, statusMessage: "Payload Too Large" });
+  }
+  const target = resolveTarget(event);
+  const state = { tooLarge: false };
+  const body = limitBody(event, state);
+  return fetch(target, {
+    body,
+    duplex: body ? "half" : void 0,
+    // streamed request body
+    headers: buildHeaders(event, target),
+    method: event.method,
+    redirect: "manual"
+  }).catch((reason) => {
+    if (state.tooLarge) throw createError({ statusCode: 413, statusMessage: "Payload Too Large" });
+    throw createError({ cause: reason, statusCode: 502, statusMessage: "PostHog unreachable" });
+  }).then((response) => {
+    setResponseStatus(event, response.status, response.statusText);
+    setResponseHeaders(event, Object.fromEntries(RESPONSE_HEADERS.filter((name) => response.headers.has(name)).map((name) => [name, response.headers.get(name)])));
+    return response.body ? sendStream(event, response.body) : send(event, "");
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@merkaly/nuxt",
-  "version": "0.10.5",
+  "version": "0.11.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/merkaly-io/nuxt.git"
@@ -57,6 +57,7 @@
     "gsap": "^3.15.0",
     "notivue": "^2.4.5",
     "nuxt": "^4.6.3",
+    "posthog-js": "^1.446.0",
     "reflect-metadata": "^0.2.2",
     "sass": "^1.107.1",
     "typescript": "~5.9.3",