@mvtlab/nextjs-orchestrator

v0.2.0

Published

a month ago

Next.js SDK to integrate the MVT Lab CDN engine with optional anti-flicker support.

0High
0Medium
0Low

n33t3sh

nextjs mvt ab-testing cdn-engine

@mvtlab/nextjs-orchestrator

React SDK for integrating the MVTLab.io CDN engine into Next.js applications with anti-flicker support.

Installation

npm install @mvtlab/nextjs-orchestrator
# or
yarn add @mvtlab/nextjs-orchestrator

Requirements: Next.js >= 13.0.0, React >= 18.0.0

Quick Start

Recommended — App Router (SSR-safe, no flicker)

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.

// app/layout.tsx
import { MVTScripts } from '@mvtlab/nextjs-orchestrator';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <MVTScripts orchestratorKey="YOUR_PROJECT_KEY" />
        {children}
      </body>
    </html>
  );
}

That's it. No 'use client' required.

Pages Router

// pages/_app.tsx
import { MVTOrchestrator } from '@mvtlab/nextjs-orchestrator';

export default function MyApp({ Component, pageProps }) {
  return (
    <MVTOrchestrator orchestratorKey="YOUR_PROJECT_KEY">
      <Component {...pageProps} />
    </MVTOrchestrator>
  );
}

Components

`MVTScripts` — Server Component ✅ Recommended

Place once at the top of <body> in your root layout.tsx.

Renders two script tags directly into the server HTML:

An inline anti-flicker script that sets body { opacity: 0 } and exposes window.rmfk() — runs synchronously before any page content is visible.
The MVT engine <script async> that loads the CDN, applies variant changes, then calls window.rmfk() to reveal the page.

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 |

`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.

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.

import { MVTOrchestrator } from '@mvtlab/nextjs-orchestrator';

<MVTOrchestrator
  orchestratorKey="YOUR_PROJECT_KEY"
  antiFlickerEnabled={true}       // default
  antiFlickerTimeoutMs={3000}     // default
>
  {children}
</MVTOrchestrator>

| 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

// .env.local
NEXT_PUBLIC_MVT_PROJECT_KEY=your_key_here

<MVTScripts orchestratorKey={process.env.NEXT_PUBLIC_MVT_PROJECT_KEY!} />

Disable anti-flicker

<MVTScripts orchestratorKey="abc123xyz" antiFlickerEnabled={false} />

Custom timeout

<MVTScripts orchestratorKey="abc123xyz" antiFlickerTimeoutMs={5000} />

TypeScript

import type { MVTScriptsProps, MVTOrchestratorProps } from '@mvtlab/nextjs-orchestrator';

How It Works

`MVTScripts` (Server Component)

Server-renders two <script> tags into the HTML response:

<!-- 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

`MVTOrchestrator` (Client Component)

Injects the same scripts via useEffect (after hydration). Detects if MVTScripts already ran (id="mvt-engine-script" present) and skips re-injection.

Sequence when standalone: SSR renders → hydration → useEffect → scripts injected

Anti-Flicker Detail

<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

Troubleshooting

Engine not loading?

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)?

Switch from MVTOrchestrator to MVTScripts in layout.tsx — the client-side approach cannot prevent the initial SSR flash
Confirm antiFlickerEnabled={true} (default)

Duplicate scripts in DOM?

Use MVTScripts or MVTOrchestrator once at root, not both independently
If using both together, MVTOrchestrator auto-detects MVTScripts and skips injection

Pages Router / no layout.tsx?

Use MVTOrchestrator in pages/_app.tsx

FAQ

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 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. Experiment variants won't be applied.

TypeScript support? Full type definitions included. Both MVTScriptsProps and MVTOrchestratorProps are exported.

Browser support? Modern browsers with ES2019+, React 18+, and standard DOM APIs.

License

See LICENSE for details.

Support

GitHub: MVT-Lab/nextjs-orchestrator
MVTLab.io: Contact your representative

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@mvtlab/nextjs-orchestrator

Installation

Quick Start

Recommended — App Router (SSR-safe, no flicker)

Pages Router

Components

MVTScripts — Server Component ✅ Recommended

MVTOrchestrator — Client Component

Usage Examples

With environment variable

Disable anti-flicker

Custom timeout

TypeScript

How It Works

MVTScripts (Server Component)

MVTOrchestrator (Client Component)

Anti-Flicker Detail

Troubleshooting

FAQ

License

Support

`MVTScripts` — Server Component ✅ Recommended

`MVTOrchestrator` — Client Component

`MVTScripts` (Server Component)

`MVTOrchestrator` (Client Component)