App

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

React

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 React 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-react, 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
    Set up a React application using Vite

    Run the following commands to create a new React application using Vite:

    terminal
    npm create vite@latest monocle-react -- --template react-ts
    cd monocle-react
    npm install
  2. 2
    Install @spur.us/monocle-react

    Run the following command to install the SDK:

    terminal
    npm install @spur.us/monocle-react
  3. 3
    Set your Monocle API keys

    Add your Monocle Publishable Key to your .env file or create it if it doesn't exist.

    .env
    VITE_MONOCLE_PUBLISHABLE_KEY=<MONOCLE PUBLISHABLE KEY>
  4. 4
    Add MonocleProvider to your app

    Wrap the section from which you wish to access Monocle with the MonocleProvider component.

    tsx
    import { StrictMode } from "react";
    import { createRoot } from "react-dom/client";
    import "./index.css";
    import App from "./App.tsx";
    import { MonocleProvider } from "@spur.us/monocle-react";
    

    const PUBLISHABLE_KEY = import.meta.env.VITE_MONOCLE_PUBLISHABLE_KEY;
    

    if (!PUBLISHABLE_KEY) {
      throw new Error("Add your Monocle Publishable Key to the .env file");
    }
    

    createRoot(document.getElementById("root")!).render(
      <StrictMode>
        <MonocleProvider publishableKey={PUBLISHABLE_KEY}>
          <App />
        </MonocleProvider>
      </StrictMode>,
    );

Session-Level Analysis (Optional)

  1. 5
    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
    import { useMonocle } from "@spur.us/monocle-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. 6
    Install the backend package

    Use the @spur.us/monocle-backend package to decrypt the assessment in your Node.js backend.

    terminal
    npm install @spur.us/monocle-backend
  3. 7
    Add your secret key

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

    .env
    VITE_MONOCLE_PUBLISHABLE_KEY=<MONOCLE PUBLISHABLE KEY>
    MONOCLE_SECRET_KEY=<your-secret-key>
  4. 8
    Decrypt the assessment

    Decrypt the assessment in your backend using the monocle client.

    javascript
    const { createMonocleClient } = require("@spur.us/monocle-backend");
    const express = require("express");
    

    const app = express();
    

    app.post("/api/submit", express.json(), async (req, res) => {
      const { monocle } = req.body;
    

      try {
        const monocleClient = await createMonocleClient({
          secretKey: process.env.MONOCLE_SECRET_KEY,
        });
        const decryptedAssessment = await monocleClient.decryptAssessment(monocle);
        // Handle decrypted assessment
      } catch (error) {
        // Handle error
      }
    });

Related