Implementation with Nuxt

Integrate Nuxt 4 with Kameleoon Web Experimentation. This guide covers the steps to preload the Kameleoon engine with anti-flicker protection and execute the engine.js script after client hydration. This setup ensures optimal performance, visual stability, and compatibility with the Nuxt rendering lifecycle. Access reference implementations for:

Access the production-ready Nuxt 4 integration

Find the production-ready repository here: https://github.com/Kameleoon/setup-engine-nuxt-4 Before starting, replace the sitecode value in integrations/Kameleoon/sitecode.ts.

Depending on when you created your Kameleoon project, your scripts may reside on kameleoon.eu or kameleoon.io. Always use the domain from your project settings in the Kameleoon App.

Overview

Workflow

Phase	Description	Component
SSR Rendering	Inject the preload link and anti-flicker CSS	`KameleoonHead.vue`
Client Hydration	Vue hydrates the DOM	—
Post Hydration	Load the Kameleoon engine asynchronously	`KameleoonScriptLoader.client.vue`
Fallback Safe-Exit	Remove anti-flicker CSS if the script fails or stalls	`KameleoonScriptLoader.client.vue`

Quick setup

Add the integrations/Kameleoon folder to your Nuxt project.
Import and register both integration components in your layout (we recommend layouts/default.vue). See: Usage in default.vue.

Components

The integration uses two Vue components executed at different stages of the Nuxt rendering pipeline:

Component	Execution Context	Purpose
`KameleoonHead.vue`	Server-side (SSR)	Injects the preload directive and anti-flicker CSS before hydration
`KameleoonScriptLoader.client.vue`	Client-side (post hydration)	Loads the engine script and manages the anti-flicker timeout

This approach provides fast rendering, stable UI behavior, and full compatibility with Nuxt hydration.

1. `KameleoonHead.vue`

KameleoonHead.vue runs only during server-side rendering. It prepares the page for a flicker-free experience by:

Injecting anti-flicker CSS during SSR.
Preloading the Kameleoon engine (engine.js) so the browser fetches it early.

<script setup>
import { SITECODE_SRC } from "../sitecode";
</script>

<template>
    <Head>
        <!-- preload script early -->
        <Link rel="preload" :href="SITECODE_SRC" as="script" fetchpriority="high" />

        <!-- anti-flicker CSS -->
        <Style id="kameleoonLoadingStyleSheet">
            html::after { content: ''; position: fixed; inset: 0; background: #fff; z-index: 2147483647; }
        </Style>
    </Head>
</template>

See KameleoonHead.vue on GitHub.

2. `KameleoonScriptLoader.client.vue`

KameleoonScriptLoader.client.vue executes on the client after hydration. The component:

Removes the anti-flicker stylesheet when the page is ready.
Loads the engine.js script dynamically.
Handles timing and fallback behavior for slow script loading.

<script setup>
defineOptions({ name: "KameleoonScriptLoader" });

import { nextTick, onMounted } from "vue";
import { SITECODE_SRC } from "~/integrations/Kameleoon/sitecode";

onMounted(async () => {
    await nextTick();

    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 alreadyLoaded = document.querySelector(`script[src*="${SITECODE_SRC}"]`);
    if (!alreadyLoaded) {
        const script = document.createElement("script");
        script.src = SITECODE_SRC;
        script.async = true;
        document.head.appendChild(script);
    }
});
</script>

<template>
    <!-- nothing rendered -->
</template>

See KameleoonScriptLoader.client.vue on GitHub.

The default anti-flicker timeout is 750 ms. Adjust kameleoonLoadingTimeout as needed.

Usage in `default.vue`

Use the following example to combine components in your layout:

<script setup>
import KameleoonHead from "~/integrations/Kameleoon/components/KameleoonHead.vue";
import KameleoonScriptLoader from "~/integrations/Kameleoon/components/KameleoonScriptLoader.client.vue";
</script>

<template>
    <!-- SSR: preload + anti-flicker -->
    <KameleoonHead />

    <!-- Client: load script after hydration -->
    <KameleoonScriptLoader />

    <!-- Layout UI -->
    <div class="min-h-screen bg-background font-inter">
        <Navigation />

        <main class="container mx-auto px-4 py-8">
            <NuxtPage />
        </main>
    </div>
</template>

See default.vue on GitHub.

Key takeaways

Prevent hydration mismatch warnings.
Ensure a flicker-free experience before Kameleoon initialization.
Load the script only once, including during SPA navigation.
Maintain compatibility with layouts, pages, dynamic routes, and conditional rendering.

With this configuration, your Nuxt application loads and executes Kameleoon reliably without affecting rendering stability.

Home

Web experimentation

Feature experimentation

Core concepts

Privacy and compliance

Developer tools

Implementation with Nuxt

Implementation with Nuxt

Access the production-ready Nuxt 4 integration

Overview

Workflow

Quick setup

Components

1. `KameleoonHead.vue`

2. `KameleoonScriptLoader.client.vue`

Usage in `default.vue`

Key takeaways

​Implementation with Nuxt

​Access the production-ready Nuxt 4 integration

​Overview

​Workflow

​Quick setup

​Components

​1. KameleoonHead.vue

​2. KameleoonScriptLoader.client.vue

​Usage in default.vue

​Key takeaways

Implementation with Nuxt

Access the production-ready Nuxt 4 integration

Overview

Workflow

Quick setup

Components

1. `KameleoonHead.vue`

2. `KameleoonScriptLoader.client.vue`

Usage in `default.vue`

Key takeaways