All Collections
FAQs & Troubleshooting
Adding Mutiny to a site using a rehydration framework
Adding Mutiny to a site using a rehydration framework

Learn how to install Mutiny on a site using a rehydration framework.

Updated over a week ago

Rehydration frameworks (i.e. Gatsby, Next.js) are open-source framework for static site generation. Mutiny will work with these sites, but you need to ensure that the client is installed correctly first. If you haven't done so yet, it may be helpful to familiarize yourself with how the Mutiny client works first.

How does Mutiny handle rehydration mismatches?

When server-side rendering, the content rendered to static HTML must typically match the initial state of the application after it’s first render. Other personalization tools attempt to mitigate this problem by providing a hook that can be called to render personalizations after rehydration such that hydration is unaffected, however this approach can significantly impact the Largest Contentful Paint of a page particularly of larger sites (as content rendering is delayed).

Rather than directly changing the existing content on the page, Mutiny instead hides all personalized elements with CSS, before cloning and re-rendering elements within a Web Component to then apply changes to. These web components are invisible to virtual DOM implementations such that when app frameworks rehydrate the website, it matches only content it has rendered and not Mutiny content dispersed throughout the page. This allows Mutiny to render prior to hydration without encountering mismatches, significantly benefiting performance.

Script API (not recommended)

Often times, these frameworks will use a Script API (example from Next.js here) feature that allows you to load scripts on your site performantly. In most cases, it's recommended that scripts are loaded after the bulk of a web page has been loaded so that a user can begin interacting with and using your website before the browser starts to load extra scripts. These script APIs often default to loading scripts in this manner when your script tag is loaded using the <Script> component (note the uppercase "S")

With Mutiny, it's vital that the client script is loaded as early as possible in your site's rendering to ensure that your page doesn't flicker when Mutiny experiences are loaded.

Installing the Mutiny client code

In order to ensure the Mutiny client is installed correctly, we recommend avoiding the Script API, and instead loading the Mutiny client with a regular <script> tag (note the lowercase "s"), and that the script is added as high up in the <head> tag as possible.

Many of these rehydration frameworks have a "Head API" just for the purpose of appending items to the <head> of the page (here are examples from Gatsby and Next.js). You can find more information about installing the Mutiny client here.

Don't be a stranger

If you have any questions, we’re here to help! Please feel free to contact us at any time, either through intercom chat or via

Did this answer your question?