npm - @mvtlab/nextjs-orchestrator - Versions diffs - 0.1.3 → 0.2.0 - Mend

@mvtlab/nextjs-orchestrator 0.1.3 → 0.2.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 (8) hide show

package/README.md CHANGED Viewed

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@mvtlab/nextjs-orchestrator.svg)](https://www.npmjs.com/package/@mvtlab/nextjs-orchestrator)
 [![License](https://img.shields.io/npm/l/@mvtlab/nextjs-orchestrator.svg)](LICENSE)
-React component for integrating MVTLab.io CDN engine into Next.js applications with optional anti-flicker support.
+React SDK for integrating the MVTLab.io CDN engine into Next.js applications with anti-flicker support.
 ---
@@ -22,35 +22,34 @@ yarn add @mvtlab/nextjs-orchestrator
 ## Quick Start
-Wrap your app at the root level. The component must be in a client component file (`'use client';`).
+### Recommended — App Router (SSR-safe, no flicker)
-### App Router
+Use `MVTScripts` in your root `layout.tsx`. It is a **Server Component** — no `'use client'`
+needed — so the anti-flicker style and engine script are injected into the server-rendered
+HTML and execute before React hydration, preventing any content flash.
 ```tsx
 // app/layout.tsx
-'use client';
-import { MVTOrchestrator } from '@mvtlab/nextjs-orchestrator';
+import { MVTScripts } from '@mvtlab/nextjs-orchestrator';
 export default function RootLayout({ children }) {
   return (
     <html lang="en">
       <body>
-        <MVTOrchestrator orchestratorKey="YOUR_PROJECT_KEY">
-          {children}
-        </MVTOrchestrator>
+        <MVTScripts orchestratorKey="YOUR_PROJECT_KEY" />
+        {children}
       </body>
     </html>
   );
 }
 ```
+That's it. No `'use client'` required.
 ### Pages Router
 ```tsx
 // pages/_app.tsx
-'use client';
 import { MVTOrchestrator } from '@mvtlab/nextjs-orchestrator';
 export default function MyApp({ Component, pageProps }) {
@@ -62,150 +61,192 @@ export default function MyApp({ Component, pageProps }) {
 }
 ```
-> **Why `'use client'`?** The component injects scripts and styles, accesses `window`/`document`, and defines `window.rmfk`—all browser-only operations that can't run in server components.
 ---
-## API
+## Components
-### Props
+### `MVTScripts` — Server Component ✅ Recommended
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `orchestratorKey` | `string` | ✅ | - | MVTLab.io project key (passed as `data-project-key`) |
-| `children` | `ReactNode` | ✅ | - | App content to wrap |
-| `antiFlickerEnabled` | `boolean` | ❌ | `true` | Inject temporary `body{opacity:0}` style until engine ready |
-| `antiFlickerTimeoutMs` | `number` | ❌ | `3000` | Fallback timeout to remove anti-flicker style |
+Place once at the top of `<body>` in your root `layout.tsx`.
-### TypeScript
+Renders two script tags directly into the server HTML:
+1. An **inline anti-flicker script** that sets `body { opacity: 0 }` and exposes
+   `window.rmfk()` — runs synchronously before any page content is visible.
+2. The **MVT engine `<script async>`** that loads the CDN, applies variant changes,
+   then calls `window.rmfk()` to reveal the page.
 ```tsx
-import type { MVTOrchestratorProps } from '@mvtlab/nextjs-orchestrator';
+import { MVTScripts } from '@mvtlab/nextjs-orchestrator';
+<MVTScripts
+  orchestratorKey="YOUR_PROJECT_KEY"
+  antiFlickerEnabled={true}       // default
+  antiFlickerTimeoutMs={3000}     // default
+/>
 ```
----
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `orchestratorKey` | `string` | — | MVTLab project key |
+| `antiFlickerEnabled` | `boolean` | `true` | Inject `body{opacity:0}` before hydration |
+| `antiFlickerTimeoutMs` | `number` | `3000` | Fallback timeout to reveal page if engine stalls |
+| `engineUrl` | `string` | staging CDN URL | Override engine script URL |
-## Usage Examples
+### `MVTOrchestrator` — Client Component
+A `'use client'` component that handles script injection client-side and enforces a single
+project key per page. Use this for **Pages Router** apps or when you cannot modify `layout.tsx`.
-### Basic
+> **Note:** When used without `MVTScripts` in layout, the anti-flicker fires after React
+> hydration and will not prevent the initial SSR content flash. For full flicker prevention
+> use `MVTScripts` in `layout.tsx`.
+>
+> When used **together with `MVTScripts`**, `MVTOrchestrator` automatically detects the
+> server-injected script and skips re-injection — no duplicate scripts.
 ```tsx
-<MVTOrchestrator orchestratorKey="abc123xyz">
-  <YourApp />
+import { MVTOrchestrator } from '@mvtlab/nextjs-orchestrator';
+<MVTOrchestrator
+  orchestratorKey="YOUR_PROJECT_KEY"
+  antiFlickerEnabled={true}       // default
+  antiFlickerTimeoutMs={3000}     // default
+>
+  {children}
 </MVTOrchestrator>
 ```
-### Disable Anti-Flicker
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `orchestratorKey` | `string` | — | MVTLab project key |
+| `children` | `ReactNode` | — | App content to wrap |
+| `antiFlickerEnabled` | `boolean` | `true` | Enable anti-flicker |
+| `antiFlickerTimeoutMs` | `number` | `3000` | Fallback timeout |
+| `engineUrl` | `string` | staging CDN URL | Override engine script URL |
+---
+## Usage Examples
+### With environment variable
 ```tsx
-<MVTOrchestrator
-  orchestratorKey="abc123xyz"
-  antiFlickerEnabled={false}
->
-  <YourApp />
-</MVTOrchestrator>
+// .env.local
+NEXT_PUBLIC_MVT_PROJECT_KEY=your_key_here
+```
+```tsx
+<MVTScripts orchestratorKey={process.env.NEXT_PUBLIC_MVT_PROJECT_KEY!} />
 ```
-### Custom Timeout
+### Disable anti-flicker
 ```tsx
-<MVTOrchestrator
-  orchestratorKey="abc123xyz"
-  antiFlickerTimeoutMs={5000}
->
-  <YourApp />
-</MVTOrchestrator>
+<MVTScripts orchestratorKey="abc123xyz" antiFlickerEnabled={false} />
 ```
-### Environment Variables
+### Custom timeout
 ```tsx
-// .env.local
-NEXT_PUBLIC_MVT_PROJECT_KEY=your_key_here
+<MVTScripts orchestratorKey="abc123xyz" antiFlickerTimeoutMs={5000} />
 ```
+### TypeScript
 ```tsx
-<MVTOrchestrator
-  orchestratorKey={process.env.NEXT_PUBLIC_MVT_PROJECT_KEY!}
->
-  {children}
-</MVTOrchestrator>
+import type { MVTScriptsProps, MVTOrchestratorProps } from '@mvtlab/nextjs-orchestrator';
 ```
 ---
 ## How It Works
-### Script Injection
+### `MVTScripts` (Server Component)
+Server-renders two `<script>` tags into the HTML response:
+```html
+<!-- Anti-flicker: runs synchronously before any content is shown -->
+<script id="mvt-anti-flicker">
+  var timeout=3000;!(function(h,i,d,e){ ... body{opacity:0} ... window.rmfk ... })(...)
+</script>
+<!-- Engine: async, loads CDN, applies variants, calls window.rmfk() -->
+<script
+  id="mvt-engine-script"
+  src="https://staging-svc.mvtlab.io/scripts/engine.js"
+  data-project-key="YOUR_KEY"
+  data-mvt="engine"
+  data-mvt-engine="true"
+  data-flicker-class="abtest-hidden"
+  crossorigin="anonymous"
+  async
+></script>
+```
+Sequence: **body hidden → engine loads → variants applied → body revealed**
-On mount (client-side only via `useEffect`):
+### `MVTOrchestrator` (Client Component)
-1. Checks for existing script with `id="mvt-engine-script"`
-2. If missing, creates `<script>` with:
-   - `src="https://staging-svc.mvtlab.io/scripts/engine.js"`
-   - `data-project-key={orchestratorKey}`
-   - `data-mvt="engine"`
-   - `async={true}`
-3. Appends to `<head>`
+Injects the same scripts via `useEffect` (after hydration). Detects if `MVTScripts` already
+ran (`id="mvt-engine-script"` present) and skips re-injection.
-This ensures **one script per page**, even on re-renders.
+Sequence when standalone: **SSR renders → hydration → useEffect → scripts injected**
-### Anti-Flicker
+### Anti-Flicker Detail
-When `antiFlickerEnabled={true}`:
+- `<style id="abhide">body{opacity:0}</style>` is injected into `<head>`
+- `window.rmfk()` is defined to remove that style element
+- The engine calls `window.rmfk()` once variants are applied
+- A safety timeout removes the style if the engine never responds
-1. Injects `<style id="abhide">body{opacity:0}</style>` into `<head>`
-2. Defines `window.rmfk()` to remove the style element
-3. Engine calls `window.rmfk()` when ready
-4. Safety timeout (default 3000ms) calls `window.rmfk()` as fallback
+---
-The `id="abhide"` matches the original HTML snippet's style identifier. The function name `rmfk` stands for "remove flicker"—a callback the engine uses to signal readiness.
+## Troubleshooting
-### Project Key Validation
+**Engine not loading?**
-- Stores `orchestratorKey` in `window.__mvtOrchestratorKey` on mount
-- If a different key is detected, logs error and skips script injection
-- Enforces **one key per website** (wrap once at root)
+- Verify `orchestratorKey` is the correct project key from your MVTLab dashboard
+- Check the Network tab for the `engine.js` request and any errors
+- Ensure the project's domain matches the `websiteUrl` configured in MVTLab
----
+**Anti-flicker not working (page flashes)?**
-## Troubleshooting
+- Switch from `MVTOrchestrator` to `MVTScripts` in `layout.tsx` — the client-side approach cannot prevent the initial SSR flash
+- Confirm `antiFlickerEnabled={true}` (default)
-**Script not loading?**
-- Ensure `'use client';` is present
-- Verify `orchestratorKey` is correct
-- Check browser console for errors
+**Duplicate scripts in DOM?**
-**Anti-flicker not working?**
-- Confirm `antiFlickerEnabled={true}`
-- Check if `window.rmfk()` is called (inspect console)
-- Increase `antiFlickerTimeoutMs` if engine loads slowly
+- Use `MVTScripts` or `MVTOrchestrator` once at root, not both independently
+- If using both together, `MVTOrchestrator` auto-detects `MVTScripts` and skips injection
-**Multiple scripts?**
-- Use `MVTOrchestrator` only once at root
-- Don't use different keys on the same page
+**Pages Router / no layout.tsx?**
-**SSR errors?**
-- All DOM access is in `useEffect` (browser-only)
-- Ensure `'use client';` is at the top of the file
+- Use `MVTOrchestrator` in `pages/_app.tsx`
 ---
 ## FAQ
-**Is this SSR-safe?**
-Yes. DOM operations run in `useEffect`, which only executes in the browser. Server renders `{children}`; script injection is client-only.
+**Do I need `'use client'` with `MVTScripts`?**
+No. `MVTScripts` is a Server Component. Add it directly to your `layout.tsx` without any directive.
+**Can I use `MVTScripts` and `MVTOrchestrator` together?**
+Yes. Put `MVTScripts` in `layout.tsx` for correct timing and use `MVTOrchestrator` elsewhere for
+client-side key enforcement. The orchestrator detects the server-injected script and won't duplicate it.
-**Can I use multiple project keys?**
-No. Use one `orchestratorKey` at the root for the entire website. Different keys on the same page will log an error.
+**Can I use multiple project keys?**
+No. Use one `orchestratorKey` for the entire site. Different keys on the same page will log an error.
-**What if the engine fails to load?**
-The timeout (default 3000ms) removes the anti-flicker style, so the page becomes visible. Engine features won't be available.
+**What if the engine fails to load?**
+The timeout (default 3000ms) removes the anti-flicker style so the page becomes visible.
+Experiment variants won't be applied.
-**TypeScript support?**
-Full type definitions included. Import `MVTOrchestratorProps` for type checking.
+**TypeScript support?**
+Full type definitions included. Both `MVTScriptsProps` and `MVTOrchestratorProps` are exported.
-**Browser support?**
+**Browser support?**
 Modern browsers with ES2019+, React 18+, and standard DOM APIs.
 ---
@@ -225,4 +266,6 @@ See [LICENSE](LICENSE) for details.
 ---
-*This package wraps the standard MVTLab.io HTML integration snippet into a React component. The original snippet uses an IIFE pattern with `document`, `window`, and a timeout—this SDK translates that into React hooks and TypeScript types.*
+*`MVTScripts` renders the standard MVTLab.io HTML snippet server-side so it runs before
+hydration. `MVTOrchestrator` translates the same snippet into React hooks for client-side
+or Pages Router use.*

package/dist/MVTOrchestrator.d.ts CHANGED Viewed

@@ -7,8 +7,12 @@ export type MVTOrchestratorProps = {
     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.
+     * When enabled and MVTScripts is NOT present in layout.tsx, a temporary
+     * style is applied client-side to hide the body until the engine removes it.
+     * Note: when used standalone (without MVTScripts), anti-flicker fires after
+     * React hydration and will not prevent the initial SSR content flash.
+     * For full flicker prevention use MVTScripts in your root layout.tsx instead.
+     * Defaults to true.
      */
     antiFlickerEnabled?: boolean;
     /**

package/dist/MVTOrchestrator.js CHANGED Viewed

@@ -8,48 +8,62 @@ export const MVTOrchestrator = ({ orchestratorKey, antiFlickerEnabled = true, an
         if (typeof window === 'undefined' || typeof document === 'undefined') {
             return;
         }
-        // Anti-flicker: inject style to hide body and set up removal function
+        // Detect whether MVTScripts server component already injected the engine.
+        // If the <script id="mvt-engine-script"> is present, the server-side path
+        // ran (correct timing). We skip script injection but still ensure window.rmfk
+        // is available for the engine to call and set the timeout fallback.
+        const engineAlreadyInjected = !!document.getElementById('mvt-engine-script');
+        // Anti-flicker: only inject client-side when MVTScripts was NOT used.
+        // When MVTScripts is in layout.tsx the anti-flicker script is server-rendered
+        // and window.rmfk is already defined — we just need to set the timeout fallback.
         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);
+            if (!engineAlreadyInjected) {
+                // Standalone mode: inject anti-flicker client-side (fires after hydration —
+                // does not prevent the initial SSR flash, but still protects against variant
+                // flicker on client-side navigations).
+                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
+            // Expose window.rmfk so the engine can remove the anti-flicker style.
+            // MVTScripts also defines this via the inline script; redefining here is safe.
             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
+            // Safety timeout: remove anti-flicker if the engine never calls rmfk.
             window.setTimeout(() => {
-                if (typeof window.rmfk === 'function') {
-                    window.rmfk();
+                const rmfk = window.rmfk;
+                if (typeof rmfk === 'function') {
+                    rmfk();
                 }
             }, antiFlickerTimeoutMs);
         }
-        // Enforce a single project key per page
-        const globalKeyProp = '__mvtOrchestratorKey';
         const w = window;
-        if (w[globalKeyProp] && w[globalKeyProp] !== orchestratorKey) {
+        if (w.__mvtOrchestratorKey && w.__mvtOrchestratorKey !== 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}".`);
+                `Existing key: "${w.__mvtOrchestratorKey}", 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)) {
+        w.__mvtOrchestratorKey = orchestratorKey;
+        // Inject the engine script only when MVTScripts did not already do so.
+        if (!engineAlreadyInjected) {
             const script = document.createElement('script');
-            script.id = scriptId;
+            script.id = 'mvt-engine-script';
             script.src = engineUrl;
             script.async = true;
+            script.crossOrigin = 'anonymous';
             script.setAttribute('data-project-key', orchestratorKey);
             script.setAttribute('data-mvt', 'engine');
+            script.setAttribute('data-mvt-engine', 'true');
+            script.setAttribute('data-flicker-class', 'abtest-hidden');
             document.head.appendChild(script);
         }
     }, [orchestratorKey, antiFlickerEnabled, antiFlickerTimeoutMs, engineUrl]);

package/dist/MVTScripts.d.ts ADDED Viewed

@@ -0,0 +1,46 @@
+import React from 'react';
+export type MVTScriptsProps = {
+    /**
+     * Project key used by the MVT engine.
+     */
+    orchestratorKey: string;
+    /**
+     * Enable or disable the anti-flicker style injection.
+     * Defaults to true.
+     */
+    antiFlickerEnabled?: boolean;
+    /**
+     * Timeout in milliseconds to automatically remove the anti-flicker style
+     * if the engine never calls window.rmfk(). Defaults to 3000ms.
+     */
+    antiFlickerTimeoutMs?: number;
+    /**
+     * Custom engine script URL.
+     * Defaults to the staging endpoint.
+     */
+    engineUrl?: string;
+};
+/**
+ * Server Component — place at the top of your root layout.tsx <body>.
+ *
+ * Renders the anti-flicker inline script and the MVT engine <script> tag
+ * directly into the server-generated HTML so they execute before React
+ * hydration, eliminating the content flash that useEffect-based injection
+ * cannot prevent.
+ *
+ * Usage in app/layout.tsx:
+ *
+ *   import { MVTScripts } from '@mvtlab/nextjs-orchestrator';
+ *
+ *   export default function RootLayout({ children }) {
+ *     return (
+ *       <html>
+ *         <body>
+ *           <MVTScripts orchestratorKey="YOUR_PROJECT_KEY" />
+ *           {children}
+ *         </body>
+ *       </html>
+ *     );
+ *   }
+ */
+export declare const MVTScripts: React.FC<MVTScriptsProps>;

package/dist/MVTScripts.js ADDED Viewed

@@ -0,0 +1,34 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+const DEFAULT_ENGINE_URL = 'https://staging-svc.mvtlab.io/scripts/engine.js';
+/**
+ * Server Component — place at the top of your root layout.tsx <body>.
+ *
+ * Renders the anti-flicker inline script and the MVT engine <script> tag
+ * directly into the server-generated HTML so they execute before React
+ * hydration, eliminating the content flash that useEffect-based injection
+ * cannot prevent.
+ *
+ * Usage in app/layout.tsx:
+ *
+ *   import { MVTScripts } from '@mvtlab/nextjs-orchestrator';
+ *
+ *   export default function RootLayout({ children }) {
+ *     return (
+ *       <html>
+ *         <body>
+ *           <MVTScripts orchestratorKey="YOUR_PROJECT_KEY" />
+ *           {children}
+ *         </body>
+ *       </html>
+ *     );
+ *   }
+ */
+export const MVTScripts = ({ orchestratorKey, antiFlickerEnabled = true, antiFlickerTimeoutMs = 3000, engineUrl = DEFAULT_ENGINE_URL, }) => {
+    // Matches the exact anti-flicker snippet used in the plain HTML pages:
+    // hides body{opacity:0}, exposes window.rmfk() for the engine to call,
+    // and falls back to auto-removal after the timeout.
+    const antiFlickerHtml = `var timeout=${antiFlickerTimeoutMs};!(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");`;
+    return (_jsxs(_Fragment, { children: [antiFlickerEnabled && (
+            // eslint-disable-next-line react/no-danger
+            _jsx("script", { id: "mvt-anti-flicker", dangerouslySetInnerHTML: { __html: antiFlickerHtml } })), _jsx("script", { id: "mvt-engine-script", src: engineUrl, "data-project-key": orchestratorKey, "data-mvt": "engine", "data-mvt-engine": "true", "data-flicker-class": "abtest-hidden", crossOrigin: "anonymous", async: true })] }));
+};

package/dist/index.d.ts CHANGED Viewed

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

package/dist/index.js CHANGED Viewed

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

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@mvtlab/nextjs-orchestrator",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Next.js SDK to integrate the MVT Lab CDN engine with optional anti-flicker support.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -36,5 +36,6 @@
     "cdn-engine"
   ],
   "author": "MVT Lab",
-  "license": "MVTLab.io"
+  "license": "MVTLab.io",
+  "packageManager": "yarn@4.12.0"
 }