Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.meridial.dev/llms.txt

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

This guide shows how to instrument your Next.js app so Meridial can reliably target UI elements during walkthroughs and live support.

​
1) Install the packages

npm install @meridial/react
npm install --save-dev @meridial/swc-plugin

​
2) Enable the SWC plugin

Add the plugin to next.config.js: 
module.exports = {
  experimental: {
    swcPlugins: [
      [
        "@meridial/swc-plugin",
        {
          rootPath: process.cwd()
        }
      ]
    ]
  }
}
rootPath keeps generated IDs stable across machines by hashing relative paths instead of absolute paths.

​
3) Understand what gets stamped

The plugin writes stable data-meridial-id attributes to JSX elements at build time.
  • By default, React component call sites are stamped (for example <Button />, <Dialog />).
  • Native HTML elements are skipped unless you opt them in with allowedElements.
If you use raw HTML elements as interaction targets, configure them explicitly: 
module.exports = {
  experimental: {
    swcPlugins: [
      [
        "@meridial/swc-plugin",
        {
          rootPath: process.cwd(),
          allowedElements: ["button", "input", "a", "select", "textarea"]
        }
      ]
    ]
  }
}
For best results, custom components should spread props onto their root element so parent-level IDs pass through correctly.

​
4) Embed Voicebox in your app

Add the widget where you want in-app support to be available: 
"use client"

import { Voicebox } from "@meridial/react"

export function VoiceboxWidget({
  publishableKey,
  userId
}: {
  publishableKey: string
  userId?: string
}) {
  return (
    <Voicebox
      publishableKey={publishableKey}
      identifier={userId}
      firstMessage="Hi, I'm your assistant. How can I help?"
      instructions="You are a helpful assistant that can answer questions and guide users through the product."
      metadata={{ orgId: "org_123", plan: "pro" }}
    />
  )
}
publishableKey comes from your Meridial dashboard. Use identifier to associate sessions with a specific user.

​
5) Optional: enable authoring mode for staff

isSuperUser controls access to recorder and guide editor UI: 
<Voicebox
  publishableKey={publishableKey}
  identifier={currentUser.id}
  isSuperUser={currentUser.role === "admin"}
/>
Use this only for internal users who should record walkthroughs or edit guides.