Installation Guide

Follow these steps to integrate Mongolytics into your Next.js application. The process is designed to be as simple as possible, with distinct instructions for the App Router and Pages Router where necessary.

Step 1: Install the Package

First, install the package from NPM into your project. All required internal dependencies like `uuid` will be installed automatically.

npm install @clipper-dev/mongolytics-next

Step 2: Environment Variables

Next, you need to provide the connection details for your MongoDB database. Create a .env.local file in your project root if you don't have one already.

You can get your connection string from your MongoDB provider (e.g., a free cluster from MongoDB Atlas).

/.env.local

# .env.local

MONGOLYTICS_URI="your-mongodb-atlas-connection-string"
MONGOLYTICS_DB_NAME="your-analytics-database-name"

By default, the package will use the sessions collection. This may create a conflict with your own collections. To use a custom collection nam, simply define it in the .env.local file.

/.env.local

# .env.local

MONGOLYTICS_COLLECTION_SESSIONS="mongolytics-sessions"

Step 3: Create the API Endpoint

This single API endpoint will securely receive tracking data from your application. Choose the setup that matches your Next.js router.

For App Router (Recommended)

Create a new file at app/api/mongolytics/route.ts and export our pre-built handler.

/app/api/mongolytics/route.ts

// app/api/mongolytics/route.ts
import { mongolyticsAppRouteHandler as POST } from '@clipper-dev/mongolytics-next/server';

export { POST };

For Pages Router

Create a new file at pages/api/mongolytics.ts and export the pages-specific handler.

/pages/api/mongolytics.ts

// pages/api/mongolytics.ts
import { mongolyticsPagesRouterHandler } from '@clipper-dev/mongolytics-next/server';

export default mongolyticsPagesRouterHandler;

Step 4: Add the Tracking Component

Finally, add the <Mongolyth /> component to your root layout. This component is a client-side tracker that automatically detects page changes.

For App Router (Recommended)

Add the component directly to your app/layout.tsx file.

/app/layout.tsx

// app/layout.tsx
import { Mongolyth } from '@clipper-dev/mongolytics-next/client';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <Mongolyth />
        {children}
      </body>
    </html>
  );
}

For Pages Router

Add the component to your pages/_app.tsx file and be sure to include the routerType="pages" prop.

/pages/_app.tsx

// pages/_app.tsx
import { Mongolyth } from '@clipper-dev/mongolytics-next/client';
import type { AppProps } from 'next/app';

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <>
      <Mongolyth routerType="pages" />
      <Component {...pageProps} />
    </>
  );
}

Step 5: Verify Your Setup

That's it! To verify your installation, run your Next.js application, navigate to a few pages, and then check your MongoDB database. You should see a new collection named sessions containing your website's traffic data.