Add Live Chat to Docusaurus: 3 Clean Methods

To add live chat to Docusaurus you have three clean options: list the Talkmio script in the scripts field of docusaurus.config.js, load it from a client module so you control when it appears, or wrap the whole site with a small Root component. The first takes two minutes and suits most documentation sites. The others give you control over consent, routes and environments. This guide shows the code for each method, explains a trap that is specific to versioned documentation, and ends with a test list.

Talkmio is an AI live chat for websites. Its assistant, Mio, answers visitors from your own pages and documents in their language and hands the conversation to your team when it cannot answer. A documentation site is a natural home for it: the answers already exist, and visitors want them quickly.

Before You Start

Create a free account at app.talkmio.com, confirm your e-mail and add your website under Websites. You receive a site key and an install snippet. The examples below use the placeholder SCRIPT_ADDRESS_FROM_YOUR_SNIPPET for the script address; copy any attribute or site key exactly as your snippet shows it.

Then add your deployed documentation to the Mio knowledge base. Mio reads every public page on the same domain, respecting robots.txt. You can also add single pages, question and answer pairs, free text and files such as PDF, DOCX, TXT, MD, CSV and HTML up to 15 MB, which is handy for a changelog or a migration guide that is not part of the site.

Method 1: Add Live Chat to Docusaurus in the Config

The quickest way to add live chat to Docusaurus is the top-level scripts option. Docusaurus adds every entry to the head of each page, and an object entry lets you set attributes such as async. The Docusaurus configuration reference documents the field.

const isProd = process.env.NODE_ENV === "production";

module.exports = {
  // ...your existing config
  scripts: isProd
    ? [{ src: "SCRIPT_ADDRESS_FROM_YOUR_SNIPPET", async: true }]
    : [],
};

The production check keeps your test conversations out of the Inbox while you run npm start, and an empty array in development means no widget and no noise. Because the script is added to the generated HTML, it also loads on pages a visitor reaches directly from a search engine. If your snippet is an inline script rather than a script address, use the headTags option of recent Docusaurus versions with an innerHTML entry, or use one of the methods below.

Method 2: Load the Widget From a Client Module

If you want the script loaded in the browser under your own rules, use a client module. Register the file in the config, and export lifecycle functions that Docusaurus calls in the browser. The page on client architecture describes how client modules work.

// docusaurus.config.js
module.exports = {
  clientModules: [require.resolve("./src/clientModules/talkmio.js")],
};

// src/clientModules/talkmio.js
import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment";

if (ExecutionEnvironment.canUseDOM && process.env.NODE_ENV === "production") {
  if (!document.getElementById("talkmio-widget")) {
    const s = document.createElement("script");
    s.id = "talkmio-widget";
    s.async = true;
    s.src = "SCRIPT_ADDRESS_FROM_YOUR_SNIPPET";
    document.body.appendChild(s);
  }
}

The canUseDOM check keeps the code from running during the server-side build, where there is no document. The id guard prevents a second copy. To load the widget only after a visitor accepts cookies, move the loading code into a function and call it from your consent banner instead of at the top level. Our guide to chat widget cookies and consent explains the options.

Method 3: Wrap the Site With a Root Component

Docusaurus lets you swizzle the Root theme component, which wraps the entire site. Create src/theme/Root.js and load the script from an effect, in the same way as in any React app.

import React, { useEffect } from "react";

export default function Root({ children }) {
  useEffect(() => {
    if (process.env.NODE_ENV !== "production") return;
    if (document.getElementById("talkmio-widget")) return;
    const s = document.createElement("script");
    s.id = "talkmio-widget";
    s.async = true;
    s.src = "SCRIPT_ADDRESS_FROM_YOUR_SNIPPET";
    document.body.appendChild(s);
  }, []);
  return <>{children}</>;
}

This method is useful when you already keep site-wide logic in Root, such as consent state or feature flags, and want the loader next to it. For React-specific details about effects and strict mode, see our guide to adding live chat to Next.js, which covers the same ideas.

Which Method Should You Use?

Question	scripts config	Client module	Root component
Effort	A few lines in the config	One file and one config entry	One swizzled file
Script in static HTML	Yes	No	No
Wait for cookie consent	Awkward	Easy	Easy
Skip in development	Easy	Easy	Easy
Hide on some routes	No	With a route hook	With a location check
Best for	Most docs sites	Consent and custom rules	Sites that already use Root

If you are unsure, start with the config. It is the least code, and you can move to another method if a consent rule requires it.

The Versioned Docs Trap

Docusaurus supports documentation versions, so a site may publish the current docs and several older ones at addresses such as /docs/ and /docs/1.0.0/. That is helpful for readers, and tricky for an assistant that reads every public page on the domain. If Mio reads all versions, it may blend an answer from an old release into a question about the current one, and a developer will then follow instructions that no longer work.

There are three ways to avoid it. First, block old versions in robots.txt, since Mio respects it when it reads your site; this also helps search engines focus on the current docs. Second, add a business instruction: answer from the latest version unless the visitor names a version, and never mix steps from different versions. Third, if you only want a few versions, add single pages instead of the whole site. Test with a version-specific question using Try Mio, which shows the answer and the knowledge pieces used.

When you release a new version, use the Re-read option so Mio picks up the new pages, and review the instructions to name the new current version. Our article on AI chatbot vs site search explains how an assistant and a search box complement each other on a documentation site.

What Mio Should and Should Not Do on a Docs Site

Developers ask different questions from shoppers: how do I install, why does this error occur, which setting changes this behaviour. Mio can answer from your documentation, quote the relevant steps and point to the page. It should not guess about code it has not read, invent configuration options or promise a release date. Add instructions such as: answer only from the documentation, point to the page you used, and hand over to the team for bugs, billing and anything that needs account access.

The handoff matters on docs sites because many questions are really bug reports. Mio hands the conversation to your team when it cannot answer from your content, when the visitor asks for a person, complains or asks about a specific order. In the Inbox the chat appears with its full history, and every conversation can become a numbered ticket with a priority and status, so a real bug does not vanish in chat. For wider guidance, see our article on live chat on help center pages.

Staging, Previews and Pull Requests

Documentation teams often publish a preview for every pull request. Those previews should not load the chat against your real Inbox, or reviewers will create test conversations that your support team has to clean up. Keep the script address in an environment variable that only the production build sets, and let the config include the script only when the variable exists. In the config this is a one-line condition, and in your pipeline it is one secret that only the main branch can read.

If you want to test the widget on a preview, add a second website in your Talkmio account with its own key. A free account allows one website and paid plans allow more, so a staging website is possible when you need it. Name it clearly, so nobody mistakes it for the real one, and delete it when the preview is no longer needed.

Performance, Consent and Privacy

A chat widget is a third-party script and has a cost. The configuration above loads it asynchronously, so it does not block rendering. Docusaurus sites are static and usually fast, so measure before and after with your usual tools. The guide to live chat widget page speed shows how to test and how to delay loading until the browser is idle.

If your site shows a cookie banner or serves visitors in the European Union, decide whether the widget loads before or after consent and document your choice in your privacy notes. Talkmio stores data on servers in the EU, in Germany, and sends only conversation text and relevant knowledge base excerpts to the AI model provider. Write that accurately in your privacy page.

Test Before You Deploy

Run npm run build and serve the result with npm run serve.
Open the built site in a private window and confirm the bubble appears on the home page and on a deep documentation page.
Move between pages with the sidebar and confirm there is only one bubble.
Ask Mio three questions that your docs answer and check that each answer cites the right page.
Ask one question about an old version and confirm that it does not mix versions.
Check the browser console for blocked scripts if you use a content security policy.
Open the Visitors page in your Talkmio account and confirm you can see your own visit.

Talkmio has a Free plan with 1 operator, 1 website and 50 AI answers a month, and paid plans start with a 14-day trial. See the pricing page for current plans before you plan a large documentation site.

Frequently Asked Questions

What is the easiest way to add live chat to Docusaurus?

Add the script to the scripts field in docusaurus.config.js, with async set to true and a production check so that it does not load in development. Docusaurus adds it to every page. Use a client module or Root component only if you need consent or route rules.

Why is the chat bubble missing in development?

If you used the production check from this guide, the widget is skipped on purpose. Build the site with npm run build, serve it locally with npm run serve and test there. If it is still missing, check the console for blocked scripts and confirm the script address.

Will Mio mix answers from different doc versions?

It can if it reads all versions on your domain. Block old versions in robots.txt, tell Mio in the business instructions to answer from the latest version unless the visitor names one, and test version-specific questions with Try Mio before you launch.

How do I load the chat only after consent?

Use a client module or the Root component and call the loader from your consent handler instead of at startup. Keep the id guard so a second call does not add a second copy, and document in your privacy notes when the chat loads.

Does a chat widget slow a Docusaurus site?

It adds a third-party script, so there is some cost. Loading it asynchronously keeps it from blocking rendering. Measure your page speed before and after, and consider delaying the load until the browser is idle if your scores are tight.

Can Mio help with bug reports?

Mio can answer from your documentation, but a bug report needs a person. Mio hands over when it cannot answer from your content. Your team can convert the conversation to a numbered ticket and track it with a priority and a status.

The Bottom Line

To add live chat to Docusaurus, start with the scripts option in your config: a few lines, loaded on every page of the production build. Move to a client module or a Root component only when consent or route rules require it, and take care with versioned docs so that Mio answers from the current release. Test a production build, keep one copy of the script and review unanswered questions each week. Start free with Talkmio and let your documentation answer questions while your team sleeps.

How to Add Live Chat to Docusaurus: Config, Client Module, Root