npm - @mvtlab/nextjs-orchestrator - Versions diffs - 0.1.0 - Mend

@mvtlab/nextjs-orchestrator 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/LICENSE +10 -0
package/README.md +204 -0
package/dist/MVTOrchestrator.d.ts +29 -0
package/dist/MVTOrchestrator.js +57 -0
package/dist/index.d.ts +1 -0
package/dist/index.js +1 -0
package/package.json +30 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,10 @@
+MVTLab.io License
+Copyright (c) MVTLab.io. All rights reserved.
+This software is proprietary and confidential to MVTLab.io.
+Unauthorized copying, modification, distribution, or use of this software,
+in whole or in part, is strictly prohibited without the prior written
+consent of MVTLab.io.

package/README.md ADDED Viewed

@@ -0,0 +1,204 @@
+## `@mvtlab/nextjs-orchestrator`
+**Next.js / React SDK** to integrate the MVTLab.io CDN engine with optional anti‑flicker support.
+It wraps the plain HTML snippet:
+```html
+<script>
+  var timeout = 3000;
+  !(function (h, i, d, e) {
+    var t,
+      n = h.createElement('style');
+    (n.id = e),
+      (n.innerHTML = 'body{opacity:0}'),
+      h.head.appendChild(n),
+      (t = d),
+      (i.rmfk = function () {
+        var t = h.getElementById(e);
+        t && t.parentNode.removeChild(t);
+      }),
+      setTimeout(i.rmfk, t);
+  })(document, window, timeout, 'abhide');
+</script>
+<script
+  src="https://staging-svc.mvtlab.io/scripts/engine.js"
+  data-project-key="Kjnqjkf277nYGYUSoA0IXQ"
+  data-mvt="engine"
+></script>
+```
+into a simple React component:
+```tsx
+<MVTOrchestrator orchestratorKey="yourProjectKey" antiFlickerEnabled>
+  {children}
+</MVTOrchestrator>
+```
+---
+### Installation
+```bash
+npm install @mvtlab/nextjs-orchestrator
+# or
+yarn add @mvtlab/nextjs-orchestrator
+```
+`MVTOrchestrator` is a **client component**, so it must be used in a file marked with `'use client';`.
+> **Why client-only?**
+> The orchestrator injects `<script>` and `<style>` tags, accesses `window` and `document`, and defines `window.rmfk`.
+> These operations only exist in the browser and are not allowed in Next.js server components, so the component must run on the client.
+---
+### Quick start (Next.js App Router)
+Recommended usage is to wrap your **entire app at the root** so there is exactly **one project key per website**.
+Example in `app/layout.tsx`:
+```tsx
+'use client';
+import React from 'react';
+import { MVTOrchestrator } from '@mvtlab/nextjs-orchestrator';
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <MVTOrchestrator
+          orchestratorKey="Kjnqjkf277nYGYUSoA0IXQ"
+          antiFlickerEnabled={true}
+        >
+          {children}
+        </MVTOrchestrator>
+      </body>
+    </html>
+  );
+}
+```
+This:
+- **Injects the MVTLab.io engine script** into `<head>` once for the whole site with your project key.
+- **Optionally hides the body** until the engine is ready (anti‑flicker).
+In this setup your app has **a single `orchestratorKey` at the root**, shared across all pages.
+---
+### Usage in Next.js Pages Router
+In a classic `pages/_app.tsx`:
+```tsx
+// pages/_app.tsx
+'use client';
+import type { AppProps } from 'next/app';
+import { MVTOrchestrator } from '@mvtlab/nextjs-orchestrator';
+export default function MyApp({ Component, pageProps }: AppProps) {
+  return (
+    <MVTOrchestrator
+      orchestratorKey="Kjnqjkf277nYGYUSoA0IXQ"
+      antiFlickerEnabled={true}
+    >
+      <Component {...pageProps} />
+    </MVTOrchestrator>
+  );
+}
+```
+In this setup your app has **a single `orchestratorKey` at the root**, shared across all pages.
+---
+### Props
+- **`orchestratorKey`** (`string`, required)
+  - MVTLab.io project key.
+  - Passed to the script as `data-project-key="<orchestratorKey>"`.
+- **`antiFlickerEnabled`** (`boolean`, default `true`)
+  - When `true`, a temporary `<style id="abhide">body{opacity:0}</style>` is injected into `<head>`.
+  - This mimics the original anti‑flicker snippet and prevents users from briefly seeing the “un‑optimized” variant.
+- **`antiFlickerTimeoutMs`** (`number`, default `3000`)
+  - Timeout (in ms) after which the anti‑flicker style is removed automatically.
+  - Safety net in case the engine never calls `window.rmfk()`.
+- **`engineUrl`** (`string`, default `https://staging-svc.mvtlab.io/scripts/engine.js`)
+  - Script URL used to load the MVTLab.io engine.
+  - You can override this if you have a different environment (e.g. production).
+- **`children`** (`ReactNode`, required)
+  - The part of your app that should be orchestrated by the engine.
+  - Usually your entire app tree.
+---
+### How anti‑flicker works
+When `antiFlickerEnabled` is `true`:
+- A `<style>` tag with `id="abhide"` and `body{opacity:0}` is injected into `<head>`.
+- `window.rmfk` is defined as a function that removes that style element.
+- A timeout (`antiFlickerTimeoutMs`, default 3000ms) calls `window.rmfk()` as a fallback.
+This is a **direct React translation** of the plain HTML snippet you would otherwise manually embed.
+If you do **not** want anti‑flicker:
+```tsx
+<MVTOrchestrator orchestratorKey="yourProjectKey" antiFlickerEnabled={false}>
+  {children}
+</MVTOrchestrator>
+``>
+---
+### How script loading works
+On the client, the component:
+1. Checks for an existing `<script>` with `id="mvt-engine-script"`.
+2. If not present, it creates a new `<script>` element with:
+   - `src` = `engineUrl` (default staging URL),
+   - `data-project-key` = `orchestratorKey`,
+   - `data-mvt` = `"engine"`,
+   - `async = true`.
+3. Appends the script to `<head>`.
+This ensures **only one script is injected per page**, even if `MVTOrchestrator` is rendered multiple times.
+---
+### FAQ
+- **Is this safe with SSR?**
+  Yes. All DOM access runs inside `useEffect`, so it only executes in the browser, not during server‑side rendering.
+- **Can I use multiple project keys on the same page or site?**
+  **No.** The orchestrator is designed to be used **once at the root of your app** with a single `orchestratorKey` for the whole website.
+  Rendering with different keys on the same page is not supported and will log an error in the console as a safety check.
+- **Can I disable anti‑flicker in development?**
+  Yes, just pass `antiFlickerEnabled={false}` when you don’t need it.
+---
+### License
+This package is **licensed under MVTLab.io**.
+Copyright © MVTLab.io. All rights reserved.

package/dist/MVTOrchestrator.d.ts ADDED Viewed

@@ -0,0 +1,29 @@
+import React, { ReactNode } from 'react';
+export type MVTOrchestratorProps = {
+    /**
+     * Project key used by the MVT engine.
+     * This will be passed as data-project-key to the engine script.
+     */
+    orchestratorKey: string;
+    /**
+     * Enable or disable the anti-flicker style injection.
+     * When enabled, a temporary style is applied to hide the body until
+     * the engine (or timeout) removes it, similar to the plain HTML snippet.
+     */
+    antiFlickerEnabled?: boolean;
+    /**
+     * Timeout in milliseconds to automatically remove the anti-flicker style.
+     * Defaults to 3000ms.
+     */
+    antiFlickerTimeoutMs?: number;
+    /**
+     * Custom engine script URL.
+     * Defaults to the staging endpoint used in the original snippet.
+     */
+    engineUrl?: string;
+    /**
+     * Children that will be rendered inside the orchestrator.
+     */
+    children: ReactNode;
+};
+export declare const MVTOrchestrator: React.FC<MVTOrchestratorProps>;

package/dist/MVTOrchestrator.js ADDED Viewed

@@ -0,0 +1,57 @@
+'use client';
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect } from 'react';
+const DEFAULT_ENGINE_URL = 'https://staging-svc.mvtlab.io/scripts/engine.js';
+const ANTI_FLICKER_STYLE_ID = 'abhide';
+export const MVTOrchestrator = ({ orchestratorKey, antiFlickerEnabled = true, antiFlickerTimeoutMs = 3000, engineUrl = DEFAULT_ENGINE_URL, children, }) => {
+    useEffect(() => {
+        if (typeof window === 'undefined' || typeof document === 'undefined') {
+            return;
+        }
+        // Anti-flicker: inject style to hide body and set up removal function
+        if (antiFlickerEnabled) {
+            const existing = document.getElementById(ANTI_FLICKER_STYLE_ID);
+            if (!existing) {
+                const style = document.createElement('style');
+                style.id = ANTI_FLICKER_STYLE_ID;
+                style.innerHTML = 'body{opacity:0}';
+                document.head.appendChild(style);
+            }
+            // Expose rmfk on window to allow the engine to remove the flicker style
+            window.rmfk = function rmfk() {
+                const el = document.getElementById(ANTI_FLICKER_STYLE_ID);
+                if (el && el.parentNode) {
+                    el.parentNode.removeChild(el);
+                }
+            };
+            // Safety timeout to remove if engine never calls rmfk
+            window.setTimeout(() => {
+                if (typeof window.rmfk === 'function') {
+                    window.rmfk();
+                }
+            }, antiFlickerTimeoutMs);
+        }
+        // Enforce a single project key per page
+        const globalKeyProp = '__mvtOrchestratorKey';
+        const w = window;
+        if (w[globalKeyProp] && w[globalKeyProp] !== orchestratorKey) {
+            // eslint-disable-next-line no-console
+            console.error('[MVTOrchestrator] Multiple different project keys on the same page are not supported. ' +
+                `Existing key: "${w[globalKeyProp]}", new key: "${orchestratorKey}".`);
+            return;
+        }
+        w[globalKeyProp] = orchestratorKey;
+        // Inject the engine script only once per page load / key
+        const scriptId = 'mvt-engine-script';
+        if (!document.getElementById(scriptId)) {
+            const script = document.createElement('script');
+            script.id = scriptId;
+            script.src = engineUrl;
+            script.async = true;
+            script.setAttribute('data-project-key', orchestratorKey);
+            script.setAttribute('data-mvt', 'engine');
+            document.head.appendChild(script);
+        }
+    }, [orchestratorKey, antiFlickerEnabled, antiFlickerTimeoutMs, engineUrl]);
+    return _jsx(_Fragment, { children: children });
+};

package/dist/index.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export * from './MVTOrchestrator';

package/dist/index.js ADDED Viewed

	@@ -0,0 +1 @@
1	+ export * from './MVTOrchestrator';

package/package.json ADDED Viewed

@@ -0,0 +1,30 @@
+{
+  "name": "@mvtlab/nextjs-orchestrator",
+  "version": "0.1.0",
+  "description": "Next.js SDK to integrate the MVT Lab CDN engine with optional anti-flicker support.",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "peerDependencies": {
+    "next": ">=13.0.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "typescript": "^5.6.0"
+  },
+  "keywords": [
+    "nextjs",
+    "mvt",
+    "ab-testing",
+    "cdn-engine"
+  ],
+  "author": "MVT Lab",
+  "license": "MVTLab.io"
+}