# Add AIssue to a Next.js project

Covers the App Router on Next.js 15+. Notes for the Pages Router and Next.js 14 are at the end.

## Rules for the agent

- Make the smallest change that works. Do not refactor or reformat unrelated code.
- **Never** write the user's AIssue API token into a file, a commit, a log, or output you show. Keep it in a shell variable for this session only.
- Put the DSN in environment variables (`.env`, `.env.local`, the hosting provider's settings), not in committed code, except where a browser bundle needs it inline (the guide says when). Make sure `.env*` files are git-ignored.
- If the repository holds several applications, or the setup is unusual, ask the user which one to set up.
- If the project restricts new dependencies, ask before installing.


## Get the DSN

The DSN tells the SDK where to send errors. It looks like `https://<key>@aissue.yourgenlab.com/<number>`.

**If the user already gave you a DSN, use it and skip this section.**

Otherwise, ask the user:

> Please paste your AIssue API token. You can create one at https://aissue.yourgenlab.com/app/account/tokens.

Then, in the shell (the token stays in this session only):

```bash
export AISSUE_TOKEN='<the token the user gave you>'
curl -s https://aissue.yourgenlab.com/api/v1/domains -H "Authorization: Bearer $AISSUE_TOKEN"
```

- If one of the listed domains clearly belongs to this project, use its `id` and `dsn`.
- Otherwise create one, named after the project (for example the repository or package name):

```bash
curl -s -X POST https://aissue.yourgenlab.com/api/v1/domains \
  -H "Authorization: Bearer $AISSUE_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "<project name>"}'
```

The response contains the domain `id` and its `dsn`. If it says the plan's domain limit is reached, tell the user.


## Install

Use the project's package manager (look for `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`, or `package-lock.json`):

```bash
npm install aissue
```

## Configure

1. **Environment variables.** Add these to `.env.local` (git-ignored) and tell the user to add them to the hosting provider (for example Vercel → Settings → Environment Variables):

```bash
AISSUE_DSN=<DSN>
NEXT_PUBLIC_AISSUE_DSN=<DSN>
```

2. **Server errors.** Create `instrumentation.ts` in the project root, or in `src/` if the project uses a `src` directory:

```ts
export { register, onRequestError } from "aissue/nextjs";
```

   If `instrumentation.ts` already exists, keep its contents and merge: import `register as registerAIssue` and `onRequestError` from `"aissue/nextjs"`, call `registerAIssue()` inside the existing `register()`, and export `onRequestError`. If an `onRequestError` already exists, call AIssue's from inside it.

3. **Browser errors** (Next.js 15.3+). Create `instrumentation-client.ts` next to it:

```ts
import { initClient } from "aissue/nextjs/client";

initClient();
```

   On Next.js below 15.3, add a small client component to the root layout instead, calling `initClient()` from `"aissue/nextjs/client"` in a `useEffect`.

4. **Rendering errors.** In `app/global-error.tsx`, report the error. If the file exists, only add the import and the `useEffect`; otherwise create it:

```tsx
"use client";
import { useEffect } from "react";
import { captureException } from "aissue";

export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
  useEffect(() => {
    captureException(error);
  }, [error]);
  return (
    <html>
      <body>
        <h2>Something went wrong.</h2>
      </body>
    </html>
  );
}
```

   Route segments with their own `error.tsx` can call `captureException(error)` the same way.

Behaviour: reporting is off while `NODE_ENV` is `development` or `test`. On Vercel the deployed commit is detected automatically.

**Pages Router / Next.js 14:** server errors: call `init()` from `"aissue/node"` in `instrumentation.ts`'s `register()` (Node runtime), and wrap API routes in try/catch with `captureException`. Browser errors: call `initClient()` in `pages/_app.tsx` inside a `useEffect`.

## Source maps (readable stack traces)

Production bundles are minified, so upload their source maps for every release (the release must equal the one the SDK sends, usually the git commit SHA). Create an account API token (https://aissue.yourgenlab.com/app/account/tokens), set it as `AISSUE_TOKEN` in CI, set `productionBrowserSourceMaps: true` in `next.config.js`, then after the build:

```bash
npx aissue sourcemaps upload .next --release "$GITHUB_SHA" --domain <domain id> --delete-after
```

## Verification step

Run from the project directory after installing:

```bash
AISSUE_DSN='<DSN>' node -e "
const a = require('aissue');
a.init({ enabled: true });
try { throw new Error('AIssue setup test'); } catch (e) { a.captureException(e); }
a.flush(10000).then(ok => console.log(ok ? 'sent' : 'not sent'));
"
```

Also run the project's build (`npm run build`) to confirm the new files compile.

## Verify that errors arrive

1. Send a test error with the command in the verification step above.
2. Check that it arrived (needs the API token; if you only have a DSN, ask the user to look at their AIssue dashboard instead):

```bash
curl -s "https://aissue.yourgenlab.com/api/v1/domains/<domain id>/events?limit=5" -H "Authorization: Bearer $AISSUE_TOKEN"
```

   Look for an event titled `RuntimeError: AIssue setup test` (or `Error: AIssue setup test`). It usually appears within a few seconds.
3. Resolve the test issue so it doesn't clutter the dashboard (`issue_id` is in the event):

```bash
curl -s -X POST https://aissue.yourgenlab.com/api/v1/issues/<issue_id>/resolve -H "Authorization: Bearer $AISSUE_TOKEN"
```

If nothing arrives, check:
- the DSN is exactly right;
- the environment variable is loaded where the command ran;
- the machine can reach `aissue.yourgenlab.com`;
- the SDK isn't disabled in development (the guide says how to enable it for the test).

## Finish

Tell the user:
- which files you changed;
- that `AISSUE_DSN` (and any other variables you added) must also be set in their **production** environment, for example in the hosting provider's dashboard;
- that errors are reported from production by default, not from local development.

**Recommend connecting GitHub.** AI analyses can then point at the exact file, line and commit. It needs the user in a browser:

```bash
curl -s https://aissue.yourgenlab.com/api/v1/domains/<domain id>/github -H "Authorization: Bearer $AISSUE_TOKEN"
```

Give the user the `connect_url` from that response.

**Deployed commit.** AIssue reads the exact deployed code when the SDK knows the git commit. This is automatic on Vercel, Render, Railway, Heroku, Cloudflare Pages and GitHub Actions. With Docker or other hosts, set `AISSUE_RELEASE` to the commit SHA at deploy time, for example `--build-arg AISSUE_RELEASE=$(git rev-parse HEAD)` plus `ENV AISSUE_RELEASE=$AISSUE_RELEASE` in the Dockerfile.
