Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt

Use this file to discover all available pages before exploring further.

A production-ready integration is available in this repository: https://github.com/Kameleoon/setup-engine-nextjs Be sure to replace the sitecode with your own in src/integrations/Kameleoon/sitecode.ts.
Your Kameleoon script domain may differ between projects. Depending on their creation date, your projects may be hosted under kameleoon.eu or kameleoon.io. Always use the domain displayed for your project inside the Kameleoon App.

​
Overview​

  1. Preload the Kameleoon engine so the browser downloads it early and caches it.
  2. Apply anti-flicker CSS to hide content until the engine is ready, preventing layout shifts.
  3. Run the engine after hydration to avoid React hydration warnings or mismatches.

​
Components​

This integration uses two components that work together to ensure smooth loading and prevent flickering during hydration.

​
1. Server Component​

Place this component inside the <head> of your main layout. Its responsibilities are:
  • Injecting anti-flicker CSS during SSR to prevent UI flashing
  • Preloading the engine.js file so downloading starts as soon as possible
// ⛔ No "use client" here - must stay server-side
import { SITECODE_SRC } from "./sitecode";

const ANTIFLICKER_CSS = `
html::after {
    content: '';
    position: fixed;
    inset: 0;
    background: #fff;
    z-index: 2147483647;
}`;

export function KameleoonHead() {
    return (
        <>
            {/* Preload the engine so browser begins downloading ASAP */}
            <link rel="preload" href={SITECODE_SRC} as="script" fetchPriority="high" />
            {/* Anti-flicker stylesheet injected during SSR */}
            <style
                id="kameleoonLoadingStyleSheet"
                suppressHydrationWarning
                dangerouslySetInnerHTML={{ __html: ANTIFLICKER_CSS }}
            />
        </>
    );
}
See KameleoonHead.tsx

​
2. Client Component​

Place this component at the very top of the <body> to accurately control execution timing. This component:
  • Removes the anti-flicker styles after hydration
  • Dynamically loads Kameleoon’s engine.js
  • Ensures the script loads without blocking rendering
"use client";

import { useCallback, useEffect } from "react";
import { SITECODE_SRC } from "./sitecode";

export function KameleoonHydrationReady() {
    const removeAntiflickerStyles = useCallback(() => {
        const kameleoonLoadingTimeout = 500;
        window.kameleoonQueue = window.kameleoonQueue || [];
        window.kameleoonStartLoadTime = Date.now();

        window.kameleoonDisplayPage = function (fromEngine) {
            if (!fromEngine) {
                window.kameleoonTimeout = true;
            }
            document.getElementById("kameleoonLoadingStyleSheet")?.remove();
        };

        window.kameleoonDisplayPageTimeOut = setTimeout(
            window.kameleoonDisplayPage,
            kameleoonLoadingTimeout
        );
    }, []);

    const loadEngine = useCallback(() => {
        if (document.getElementById("kameleoon-engine")) return;

        const script = document.createElement("script");
        script.src = SITECODE_SRC;
        script.async = true;
        script.id = "kameleoon-engine";
        document.head.appendChild(script);
    }, []);

    // Execute Kameleoon after hydration
    useEffect(() => {
        removeAntiflickerStyles();
        loadEngine();
    }, [loadEngine, removeAntiflickerStyles]);

    return null;
}
See KameleoonHydrationReady.tsx
Note: The default anti-flicker timeout is 500 ms. Adjust kameleoonLoadingTimeout if needed.

​
Usage in RootLayout​

Example of how to combine both components: 
export default function RootLayout({ children }) {
    return (
        <html lang="en">
            <head>
                <KameleoonHead />
            </head>
            <body className={inter.className}>
                <KameleoonHydrationReady />
                {children}
            </body>
        </html>
    );
}
See layout.tsx

​
Key Takeaways​

  • Anti-flicker protection on SSR
  • Hydration-aware script execution
  • Asynchronous engine loading
  • Fallback timeout for reliability
  • No blocking scripts
  • Works with Next.js layouts, streaming, and React Server Components
With this setup, your Next.js application will load Kameleoon efficiently and avoid hydration-related issues.