Nextra

Nextra is a Next.js docs framework, so the snippet goes where it goes in any Next.js app: the root layout, rendered with next/script. Nextra 4 uses the App Router and app/layout.jsx; Nextra 3 uses the Pages Router and pages/_app.jsx.

Get your tracking snippet

In your Rybbit dashboard, open Site Settings → Tracking Script and copy your snippet. It looks like this:

<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>

YOUR_SITE_ID is the numeric ID of your site. If you self-host Rybbit, app.rybbit.io is the domain of your own instance.

Add the snippet to Nextra

Use the Script component with strategy="afterInteractive" rather than a plain <script> tag; the defer attribute from the snippet is not needed.

Add the Script next to the Layout in app/layout.jsx (or .tsx):

app/layout.jsx

import { Footer, Layout, Navbar } from "nextra-theme-docs";
import { Head } from "nextra/components";
import { getPageMap } from "nextra/page-map";
import Script from "next/script";
import "nextra-theme-docs/style.css";

export default async function RootLayout({ children }) {
  return (
    <html lang="en" dir="ltr" suppressHydrationWarning>
      <Head />
      <body>
        <Layout
          navbar={<Navbar logo={<b>My Docs</b>} />}
          pageMap={await getPageMap()}
          footer={<Footer>MIT {new Date().getFullYear()} © My Docs.</Footer>}
        >
          {children}
        </Layout>
        <Script
          src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Create pages/_app.jsx if your project does not have one, and render the Script beside the page:

pages/_app.jsx

import Script from "next/script";

export default function App({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
        strategy="afterInteractive"
      />
    </>
  );
}

Do not put the tag in the head option of theme.config.jsx: that option renders through next/head, and Next.js warns against loading scripts there.

Nextra navigates between pages client-side. Rybbit records those route changes as pageviews, so no extra code is needed.

Verify installation

Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

If nothing shows up:

View the page source and search for script.js?siteId= to confirm the snippet is on the page.
Open the browser Network tab and check that script.js returns 200 and that POST requests go to /api/track.
Disable ad blockers, or set up a proxy so the script loads from your own domain.
See the script troubleshooting guide for other common causes.

Troubleshooting

Only the docs pages are tracked: in Nextra 4 the tag belongs in the root app/layout.jsx, not in a nested app/docs/layout.jsx, otherwise landing pages outside docs/ are missed.
Upgrading from Nextra 3: Nextra 4 dropped the Pages Router and theme.config. Move the Script from pages/_app.jsx to app/layout.jsx as part of the migration.
Proxying through your own domain: see the Next.js guide for rewrites; every endpoint must be rewritten, not just script.js.

Next steps

Track custom events such as signups, purchases and button clicks.
Identify users to connect sessions to accounts.
Proxy the script through your own domain to bypass ad blockers.
Script attributes let you skip or mask URLs and tag events.

Get your tracking snippet

Add the snippet to Nextra

Verify installation

Troubleshooting

Next steps

On this page