App

Changelog · — A new IP page with IP history, Monocle Health Alerts, AI traffic in Explorer, and edge access tokens.

Next.js

Install with AI

If an AI coding assistant works in your repository, it can do this install for you. The prompt is generated for your app, with your publishable key already filled in; it never includes your secret key.

  1. In the Monocle dashboard, create an app and choose Next.js as the integration.
  2. On the implementation step, open the Install with AI tab. Select Copy prompt, or Download to save it as monocle-install.md in your repo.
  3. Hand the prompt to your assistant, such as Lovable, Cursor or Claude Code, with the project open.
  4. When it has finished, run the app and load a page so Monocle sends its first assessment, then return to the dashboard and select Continue. Monocle verifies the install by detecting that traffic.

The prompt covers only installing @spur.us/monocle-nextjs, adding the provider and getting traffic flowing. It tells the assistant to keep the change small, to merge the Monocle hosts into any Content Security Policy the project sets, and to stop and report rather than force a peer dependency conflict or change a project that does not match this framework. It adds no blocking and no backend decryption: session-level analysis, below, is a separate step you take once you can see your traffic.

Manual install

Follow these steps to add the SDK yourself.

  1. 1
    Install @spur.us/monocle-nextjs

    Run the following command to install the SDK:

    terminal
    npm install @spur.us/monocle-nextjs
  2. 2
    Set your Monocle API keys

    Add these keys to your .env or create the file if it doesn't exist.

    .env
    NEXT_PUBLIC_MONOCLE_PUBLISHABLE_KEY=<MONOCLE PUBLISHABLE KEY>
    MONOCLE_SECRET_KEY=<your-secret-key>
  3. 3
    Add MonocleProvider to your app

    Wrap your app with the MonocleProvider component.

    tsx
    import type { Metadata } from "next";
    import { MonocleProvider } from "@spur.us/monocle-nextjs";
    import { Geist, Geist_Mono } from "next/font/google";
    import "./globals.css";
    

    const geistSans = Geist({
      variable: "--font-geist-sans",
      subsets: ["latin"],
    });
    

    const geistMono = Geist_Mono({
      variable: "--font-geist-mono",
      subsets: ["latin"],
    });
    

    export const metadata: Metadata = {
      title: "Monocle Next.js Example",
      description: "Generate by create next app",
    };
    

    export default function RootLayout({
      children,
    }: Readonly<{
      children: React.ReactNode;
    }>) {
      return (
        <html lang="en">
          <body className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
            <MonocleProvider>{children}</MonocleProvider>
          </body>
        </html>
      );
    }

Session-Level Analysis (Optional)

  1. 4
    Add useMonocle to your form component

    Use the useMonocle hook to get the assessment and pass it with your form submission. Monocle appends the encrypted assessment when you include it in the request body.

    tsx
    "use client";
    

    import { useMonocle } from "@spur.us/monocle-nextjs";
    import { useState } from "react";
    

    export default function Form() {
      const { assessment, isLoading } = useMonocle();
    

      const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        const formData = new FormData(e.target as HTMLFormElement);
    

        await fetch("/api/submit", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            email: formData.get("email"),
            password: formData.get("password"),
            monocle: assessment,
          }),
        });
      };
    

      if (isLoading) return <div>Loading...</div>;
    

      return (
        <form onSubmit={handleSubmit}>
          <input type="email" name="email" />
          <input type="password" name="password" />
          <button type="submit">Submit</button>
        </form>
      );
    }
  2. 5
    Add your secret key

    Set your Monocle secret key as an environment variable for server-side decryption.

    .env
    NEXT_PUBLIC_MONOCLE_PUBLISHABLE_KEY=<MONOCLE PUBLISHABLE KEY>
    MONOCLE_SECRET_KEY=<your-secret-key>
  3. 6
    Decrypt the assessment

    Use monocleClient from @spur.us/monocle-nextjs/server to decrypt the assessment in your API route.

    typescript
    import { NextRequest, NextResponse } from "next/server";
    import { monocleClient } from "@spur.us/monocle-nextjs/server";
    

    export async function POST(request: NextRequest) {
      const body = await request.json();
    

      try {
        const monocle = await monocleClient();
        const decryptedAssessment = await monocle.decryptAssessment(body.monocle);
        // Handle decrypted assessment
      } catch (error) {
        // Handle error
      }
    }

Related