@mvtlab/nextjs-orchestrator
v0.1.3
Published
Next.js SDK to integrate the MVT Lab CDN engine with optional anti-flicker support.
Maintainers
n33t3shReadme
@mvtlab/nextjs-orchestrator
React component for integrating MVTLab.io CDN engine into Next.js applications with optional anti-flicker support.
Installation
npm install @mvtlab/nextjs-orchestrator
# or
yarn add @mvtlab/nextjs-orchestratorRequirements: Next.js >= 13.0.0, React >= 18.0.0
Quick Start
Wrap your app at the root level. The component must be in a client component file ('use client';).
App Router
// app/layout.tsx
'use client';
import { MVTOrchestrator } from '@mvtlab/nextjs-orchestrator';
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
<MVTOrchestrator orchestratorKey="YOUR_PROJECT_KEY">
{children}
</MVTOrchestrator>
</body>
</html>
);
}Pages Router
// pages/_app.tsx
'use client';
import { MVTOrchestrator } from '@mvtlab/nextjs-orchestrator';
export default function MyApp({ Component, pageProps }) {
return (
<MVTOrchestrator orchestratorKey="YOUR_PROJECT_KEY">
<Component {...pageProps} />
</MVTOrchestrator>
);
}Why
'use client'? The component injects scripts and styles, accesseswindow/document, and defineswindow.rmfk—all browser-only operations that can't run in server components.
API
Props
| 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 |
TypeScript
import type { MVTOrchestratorProps } from '@mvtlab/nextjs-orchestrator';Usage Examples
Basic
<MVTOrchestrator orchestratorKey="abc123xyz">
<YourApp />
</MVTOrchestrator>Disable Anti-Flicker
<MVTOrchestrator
orchestratorKey="abc123xyz"
antiFlickerEnabled={false}
>
<YourApp />
</MVTOrchestrator>Custom Timeout
<MVTOrchestrator
orchestratorKey="abc123xyz"
antiFlickerTimeoutMs={5000}
>
<YourApp />
</MVTOrchestrator>Environment Variables
// .env.local
NEXT_PUBLIC_MVT_PROJECT_KEY=your_key_here<MVTOrchestrator
orchestratorKey={process.env.NEXT_PUBLIC_MVT_PROJECT_KEY!}
>
{children}
</MVTOrchestrator>How It Works
Script Injection
On mount (client-side only via useEffect):
- Checks for existing script with
id="mvt-engine-script" - If missing, creates
<script>with:src="https://staging-svc.mvtlab.io/scripts/engine.js"data-project-key={orchestratorKey}data-mvt="engine"async={true}
- Appends to
<head>
This ensures one script per page, even on re-renders.
Anti-Flicker
When antiFlickerEnabled={true}:
- Injects
<style id="abhide">body{opacity:0}</style>into<head> - Defines
window.rmfk()to remove the style element - Engine calls
window.rmfk()when ready - 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.
Project Key Validation
- Stores
orchestratorKeyinwindow.__mvtOrchestratorKeyon mount - If a different key is detected, logs error and skips script injection
- Enforces one key per website (wrap once at root)
Troubleshooting
Script not loading?
- Ensure
'use client';is present - Verify
orchestratorKeyis correct - Check browser console for errors
Anti-flicker not working?
- Confirm
antiFlickerEnabled={true} - Check if
window.rmfk()is called (inspect console) - Increase
antiFlickerTimeoutMsif engine loads slowly
Multiple scripts?
- Use
MVTOrchestratoronly once at root - Don't use different keys on the same page
SSR errors?
- All DOM access is in
useEffect(browser-only) - Ensure
'use client';is at the top of the file
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.
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.
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.
TypeScript support?
Full type definitions included. Import MVTOrchestratorProps for type checking.
Browser support?
Modern browsers with ES2019+, React 18+, and standard DOM APIs.
License
Licensed under MVTLab.io. Copyright © MVTLab.io. All rights reserved.
See LICENSE for details.
Support
- GitHub: MVT-Lab/nextjs-orchestrator
- MVTLab.io: Contact your representative
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.