Splitlab

Documentation

How It Works

Both components load the same Splitlab engine and use the same anti-flicker mechanism — they differ only in when and where the scripts are injected.

MVTScripts (Server Component) — recommended

Server-renders two tags directly into the HTML response, so they run before React hydration:

  1. An inline anti-flicker script that injects <style id="abhide">body{opacity:0}</style> and defines window.rmfk().
  2. The engine <script async>:
    • src="https://cdn.splitlab.io/cdn/engine.js" (override with the engineUrl prop)
    • data-project-key={orchestratorKey}
    • data-mvt="engine", data-mvt-engine="true", data-flicker-class="abtest-hidden"
    • crossorigin="anonymous", async

Sequence: body hidden → engine loads → variants applied → window.rmfk() → body revealed. Because the tags are in the server HTML, there is no initial content flash.

MVTOrchestrator (Client Component)

On mount (client-side, via useEffect):

  1. Checks for an existing <script id="mvt-engine-script">. If MVTScripts already injected it server-side, MVTOrchestrator skips re-injection (no duplicate scripts).
  2. Otherwise creates the same engine <script> (same src, data-*, crossorigin, async) and appends it to <head>.
  3. Injects the anti-flicker <style id="abhide">, defines window.rmfk(), and sets a safety timeout to reveal the page if the engine never responds.

Sequence when standalone: SSR renders → hydration → useEffect → scripts injected. Because injection happens after hydration, this path does not prevent the initial SSR flash — use MVTScripts for that.

Anti-Flicker

  1. <style id="abhide">body{opacity:0}</style> hides the page.
  2. window.rmfk() removes that style element.
  3. The engine calls window.rmfk() once variants are applied.
  4. A safety timeout (default 3000ms) calls window.rmfk() as a fallback.

The id="abhide" and the function name rmfk ("remove flicker") match the standard Splitlab HTML snippet, so the deployed engine can signal readiness the same way regardless of framework.

Project Key Validation

  • MVTOrchestrator stores orchestratorKey in window.__mvtOrchestratorKey on mount.
  • If a different key is detected on the same page, it logs an error and skips injection.
  • Use one key per website — mount the component once at the root.

Technical Details

This package wraps the standard Splitlab HTML integration snippet into React. The original snippet uses an IIFE over document, window, and a timeout; MVTScripts renders it into the server HTML, while MVTOrchestrator translates it into React hooks and TypeScript types.

PreviousUsage examples
Next Troubleshooting