Nextra

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

Copy your tracking snippet

In OnyxMetric, open your site's Site Settings and copy the tracking script. It looks like this:

<script src="https://app.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID" async></script>

YOUR_SITE_ID is the numeric ID of your site.

Add the snippet to Nextra

Use Script with strategy="afterInteractive" rather than a plain <script> tag. The strategy handles timing, so async is not needed.

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

app/layout.jsx

import Script from "next/script";

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.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Create pages/_app.jsx if you do not have one, and render 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.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID"
        strategy="afterInteractive"
      />
    </>
  );
}

Do not use the head option of theme.config.jsx for this. It renders through next/head, which Next.js advises against for scripts.

Nextra navigates client-side, and those route changes are recorded as pageviews without extra code.

Check that it works

Load your live site and click through a few pages. Pageviews show up in the OnyxMetric dashboard within seconds.

If nothing arrives:

View the page source and search for script.js?siteId= to confirm the tag is present.
In the browser's Network tab, check that script.js returns 200 and that requests go to /api/track.
Turn off ad blockers, or proxy the script through your own domain.
Read script troubleshooting for other causes.

Troubleshooting

Only docs pages tracked: in Nextra 4 the tag belongs in the root app/layout.jsx, not a nested app/docs/layout.jsx, or pages outside docs/ are missed.
Upgrading from Nextra 3: Nextra 4 dropped the Pages Router and theme.config. Move Script from pages/_app.jsx to app/layout.jsx.
Own-domain proxy: the Next.js proxy guide covers rewrites. Every endpoint has to be rewritten, not only script.js.

Next steps

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

Copy your tracking snippet

Add the snippet to Nextra

Check that it works

Troubleshooting

Next steps

On this page