Skip to main content

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. The default timeout for Nuxt is 500 ms. Access reference implementations for:

Access the production-ready Nuxt 4 integration

Find the production-ready repository here: https://github.com/Kameleoon-new/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 the installation snippet on your project’s Setup tab in the Kameleoon app.

Overview

Workflow

Quick setup

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

Components

The integration uses two Vue components executed at different stages of the Nuxt rendering pipeline: 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.
See KameleoonHead.vue on GitHub.

2. KameleoonScriptLoader.client.vue

KameleoonScriptLoader.client.vue executes on the client after hydration. The component:
  • Removes the anti-flicker style sheet when the page is ready.
  • Loads the engine.js script dynamically.
  • Handles timing and fallback behavior for slow script loading.
See KameleoonScriptLoader.client.vue on GitHub.
The default timeout is 500 ms. Adjust kameleoonLoadingTimeout as needed.

Usage in default.vue

Use the following example to combine components in your layout:
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 app loads and executes Kameleoon reliably without affecting rendering stability.