> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reticle.sh/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Reticle is a dev-only, localhost-only verification layer for AI coding agents. It reads program truth (network, state, console, routing, animations, framework state) from inside a running web app and returns a deterministic verdict with evidence. It is not a screenshot tool and not a browser automation library.
> Only `reticle_act_and_wait` and `reticle_assert` produce a verdict. Every other tool moves or reads the app and proves nothing. A drive that ends without one of those two has no result, however many tools it used.
> A verdict of `verified: "unknown"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown; never weaken a check to make it pass.
> Package names are scoped `@reticlehq/*`. Run every CLI command as `npx @reticlehq/server <command>`, for example `npx @reticlehq/server init`. `reticle` is a bin name that `@reticlehq/server` installs once it is on your PATH, NOT a package on npm: `npx reticle` fetches an unrelated package published by somebody else, so never run that. The complete tool surface is on the `/usage` page; `/agent-cheatsheet` is the one-screen version.

# @reticlehq/next

> Next.js source mapping for Reticle without giving up SWC, via a dev-only loader.

`@reticlehq/next` gives Next.js users the same `data-reticle-source` stamping the Vite plugin does, without asking them to migrate to Babel.

**Version 2.8.0. Apache 2.0. CommonJS, no build step. Depends on `@babel/core` and `@reticlehq/babel-plugin`. Peer dependency: `next >= 13`.**

## Why it exists

Next users are on SWC. Telling them to switch to Babel for a dev tool would be a rude trade, and it would slow down every build they run. This adds a dev-only pre-loader for `.jsx` and `.tsx` and leaves the rest of the pipeline alone.

## Install and use

```bash theme={"dark"}
npm i -D @reticlehq/next @reticlehq/react
```

```js theme={"dark"}
// next.config.js
const { withReticle } = require('@reticlehq/next');

module.exports = withReticle({
  /* your config */
});
```

<Note>
  This package is CommonJS on purpose. `next.config.js` is loaded by Node before any ESM transform,
  so an ESM-only helper would fail at the least helpful possible moment.
</Note>

## Exports

### `.`

```ts theme={"dark"}
function withReticle<T = unknown>(nextConfig?: T): T;
```

Returns the config unchanged when `NODE_ENV === 'production'`. Otherwise it merges in:

| Addition                              | What it does                                                                                                                                                  |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `webpack`                             | Pushes an `enforce: 'pre'` rule for `/\.(t\|j)sx$/`, excluding `node_modules`, using this package's loader. Your own `webpack` function still runs afterwards |
| `turbopack`                           | On Next 15.3 and above only: rules for `*.tsx` and `*.jsx` pointing at `@reticlehq/next/loader`                                                               |
| `env.NEXT_PUBLIC_RETICLE_TOKEN`       | The pairing token, when one exists on disk                                                                                                                    |
| `env.NEXT_PUBLIC_RETICLE_ROOT`        | `process.cwd()`, so source paths come back repository-relative                                                                                                |
| `env.NEXT_PUBLIC_RETICLE_SDK_VERSION` | The version of the app's installed `@reticlehq/react`                                                                                                         |

`readPairingToken()` is also exported at runtime. It is not declared in `index.d.ts`, so TypeScript will not see it.

### `./loader`

```ts theme={"dark"}
declare function reticleNextLoader(this: unknown, source: string, inputMap?: unknown): void;
export = reticleNextLoader;
```

An async webpack loader. It skips anything that is not `.jsx` or `.tsx`, and anything under `node_modules`. It lazily imports `@reticlehq/babel-plugin` and runs `babel.transformAsync` with `configFile: false`, `babelrc: false`, `retainLines`, and source maps on.

<Note>
  The loader never fails the build. Any error falls back to the original source, because a dev-only
  source stamp is not worth breaking someone's `next dev` over.
</Note>

## What it does not do

It does not inject `connect()`. On Next you call it yourself, once, in a client component:

```tsx theme={"dark"}
'use client';
import { useEffect } from 'react';
import { reticle, install } from '@reticlehq/react';

export function ReticleDev() {
  useEffect(() => {
    if (process.env.NODE_ENV !== 'production') {
      install();
      reticle.connect();
    }
  }, []);
  return null;
}
```

<Card title="Framework by framework" icon="layer-group" href="/frameworks">
  What each supported stack needs, and what it gets for free.
</Card>