punchline!

Install

Install with AI

View as markdownOpen in ClaudeOpen in ChatGPT

Let your coding assistant (Claude Code, Cursor, Codex, Copilot or similar) install Punchline Analytics for you. Paste this prompt into it, from your project's folder:

Install Punchline Analytics in this project. Read https://punchlineanalytics.com/docs/install-with-ai.md and follow it. Before you change anything, tell me what you found and what you plan to change.

It reads the instructions below, works out how your site is built, and makes the change. If your site already has a proxy or middleware, it adds Punchline to that file instead of replacing it. You review the change, add your connection string, and deploy. Nothing runs on our side and there's no charge for it.

The connection string (PUNCHLINE_DSN) is a secret. The assistant never needs it: it leaves a blank line for you to fill in. Don't paste it into the chat.


Instructions for the coding assistant

You are adding Punchline Analytics to the user's project. Punchline runs at the edge (a Next.js proxy, a Cloudflare Worker and similar) and sends a small event for each page request after the response has gone out. It adds no script to pages and never breaks a request if it fails. Follow these steps in order.

1. Look before changing anything

  • Run git status. If there are uncommitted changes, tell the user and ask whether to continue, so your change is easy to review and undo.
  • Find out how the site is built. Read package.json (and look for wrangler.toml / wrangler.jsonc, server.ts, wp-config.php or style.css with a theme header).
  • Tell the user what you found and which install you'll use, using the table below, and wait for a go-ahead.
The project is Use Instructions
Next.js (next in package.json) the Next.js package step 2 below
A Cloudflare Worker (wrangler config) @punchline-analytics/cloudflare /docs/install-cloudflare.md, "Install with wrangler" and "Already have a Worker?"
Shopify Hydrogen (@shopify/hydrogen) withHydrogen in server.ts /docs/install-hydrogen.md
A static, Vite or Astro site deployed on Vercel, not Next.js one middleware.ts file /docs/install-vercel.md
WordPress the WordPress plugin (not code in the theme) Tell the user to follow /docs/install-wordpress.md and stop
Anything else, or the site lives on Webflow, Framer, Squarespace or Wix not a code change Tell the user to see /docs/get-started.md for the right install and stop

For anything other than Next.js, fetch the linked page (it's markdown) and follow it, then continue at step 4.

2. Next.js

  1. Install the package with the project's package manager, going by the lockfile: pnpm add for pnpm-lock.yaml, yarn add for yarn.lock, bun add for bun.lock / bun.lockb, otherwise npm install. The package is @punchline-analytics/next, version 0.6.1 or later. In a monorepo, install it in the app's own folder, not the repository root.

  2. Find the file. Look for proxy.ts, proxy.js, middleware.ts or middleware.js next to the app or pages folder: in src/ if the project uses one, otherwise at the project root.

  3. If there is none, create one. Read the major version of next in package.json. For 16 or later, create proxy.ts; for 15 or earlier, create middleware.ts and name the export middleware instead of proxy:

    import { punchline } from "@punchline-analytics/next";
    
    export const proxy = punchline();
    
    export const config = {
      matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
    };
  4. If there is one, add Punchline to it. Never create a second file or replace the user's logic. Use createTracker() as shown in /docs/install-nextjs.md, section "Already have a proxy or middleware?":

    • Create the tracker once, at module level: const tracker = createTracker();.
    • Make the function accept the event as its second argument (event: NextFetchEvent), and call tracker.track(request, event); as the first line, before any early return such as a redirect to sign-in. Requests that return before that line aren't counted.
    • Keep everything else the user's code does, unchanged.
  5. Check the matcher. Punchline only sees the paths the matcher lets through. If the existing matcher covers only part of the site (for example only /dashboard/:path* for sign-in), widen it to the one above, and wrap the user's existing logic so it still runs only on the paths it ran on before. Explain this change to the user. Next.js reads matcher at build time, so it must be a literal in the file.

3. MCP servers (if the project has one)

Look for an MCP server in the project: a route whose path ends in /mcp, or code that uses @modelcontextprotocol/sdk, mcp-handler or similar. If you find one, Punchline can record which tools agents call (/docs/mcp-analytics.md).

  • If its path ends in /mcp, there's nothing to add, as long as the matcher covers it.
  • If it's somewhere else, list it: punchline({ mcpPaths: ["/api/agents/rpc"] }), or createTracker({ mcpPaths: [...] }).

Mention to the user that tools which build something for a person (a quote, a booking, a cart) can return a handoff link, but don't add one unless they ask.

4. The connection string

  • Add a line PUNCHLINE_DSN= to .env.local (Next.js) or the project's usual local env file, and check that file is in .gitignore. Never commit a value, never put it in code, and never ask the user to paste it into the chat.
  • Tell the user to paste their connection string after the =. It was shown when they added the site in Punchline; if they no longer have it, they can rotate it in Site settings.
  • Tell them to add the same PUNCHLINE_DSN to their host for production: on Vercel, Settings → Environment Variables, then redeploy. On Cloudflare, npx wrangler secret put PUNCHLINE_DSN.

5. Check your work

  • Run the project's type check and build (or next build) and fix anything you broke.
  • Don't add the browser snippet as well, change unrelated files, or upgrade other packages.
  • Summarize what you changed, file by file, and what the user still has to do: fill in PUNCHLINE_DSN, set it on the host, deploy, then visit a few pages. Visits appear in Punchline within about a minute, and Site Doctor in the dashboard checks the install and can send a test visit.

Ask the docs

Answers come from these docs only, written by Claude (Anthropic). Your question is sent to answer it, and isn't stored.