Reference
5 min read

Advanced Web Analytics Config with @vercel/analytics

With the @vercel/analytics npm package, you are able to configure your application to send analytics data to Vercel.
Table of Contents

With the @vercel/analytics npm package you're able to configure your application to send analytics data to Vercel.

To get started with analytics, follow our Quickstart guide which will walk you through the process of setting up analytics for your project.

Override the automatic environment detection. This option allows you to force a specific environment for the package. If not defined, it will use auto which tries to set the development or production mode based on available environment variables such as NODE_ENV.

If your used framework does not expose these environment variables, the automatic detection won't work correctly. In this case, you're able to provide the correct mode manually or by other helpers that your framework exposes.

If you're using the <Analytics /> component, you can pass the mode prop to force a specific environment:

Next.js (/app)
Next.js (/pages)
Other frameworks
app/layout.tsx
'use client';
import { Analytics } from '@vercel/analytics/react';
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <head>
        <title>Next.js</title>
      </head>
      <body>
        {children}
        <Analytics mode={'production'} />;
      </body>
    </html>
  );
}

You'll see all analytics events in the browser's console with the debug mode. This option is automatically enabled if the NODE_ENV environment variable is available and either development or test.

You can manually disable it to prevent debug messages in your browsers console.

To disable the debug mode for server-side events, you need to set the VERCEL_WEB_ANALYTICS_DISABLE_LOGS environment variable to true.

Next.js (/app)
Next.js (/pages)
Other frameworks
app/layout.tsx
'use client';
import { Analytics } from '@vercel/analytics/react';
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <head>
        <title>Next.js</title>
      </head>
      <body>
        {children}
        <Analytics debug={false} />;
      </body>
    </html>
  );
}

For plain HTML sites, you have to change the script URL on your .html files:

index.html
<script defer src="https://cdn.vercel-insights.com/v1/script.debug.js"></script>

Make sure you change the URL back to /_vercel/insights/script.js when deploying to production.

With the beforeSend option, you can modify the event data before it's sent to Vercel. Below, you will see an example that ignores all events that have a /private inside the URL.

Returning null will ignore the event and no data will be sent. You can also modify the URL and check our docs about redacting sensitive data.

Next.js (/app)
Next.js (/pages)
Other frameworks
app/layout.tsx
'use client';
import { Analytics } from '@vercel/analytics/react';
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <head>
        <title>Next.js</title>
      </head>
      <body>
        {children}
        <Analytics
          beforeSend={(event) => {
            if (event.url.includes('/private')) {
              return null;
            }
            return event;
          }}
        />
      </body>
    </html>
  );
}
Last updated on May 29, 2024