Reticle Docs: verification for AI coding agents

@reticlehq/next gives a Next.js app the same data-reticle-source stamping the Vite plugin does, without asking it to migrate off SWC to Babel. Install it if your app is Next.js; on Vite use @reticlehq/vite-plugin instead. Unlike the Vite plugin it does not inject connect(), so you still call that yourself. 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, .tsx and .js files that contain JSX, and leaves the rest of the pipeline alone.

Install and use

npm i -D @reticlehq/next @reticlehq/react

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

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

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.

Exports

`.`

function withReticle<T = unknown>(nextConfig?: T, options?: { sourceMapping?: boolean }): T;

Returns the config unchanged when NODE_ENV === 'production', unless RETICLE_DEV=1 is set (for NODE_ENV=production next dev). sourceMapping: false skips the loader rules, for an app that renders through a non-DOM React reconciler. Otherwise it merges in:

Addition	What it does
`webpack`	Pushes an `enforce: 'pre'` rule for `/\.(tsx\|jsx\|js)$/`, 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` (and, on Next 16, the project’s own `*.js`) pointing at `@reticlehq/next/loader`
`allowedDevOrigins`	Your own list plus the loopback hosts a Reticle-opened tab arrives on, on a Next that accepts the key (15.2.2 and above)
`env.NEXT_PUBLIC_RETICLE_URL`	The bridge URL: a valid `RETICLE_PORT` override, otherwise project daemon discovery and `.reticle.json`
`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`

Daemon discovery reads RETICLE_STATE_DIR (default ~/.reticle). Pairing tokens use RETICLE_PAIRING_TOKEN_DIR independently. The generated ReticleDev component reads NEXT_PUBLIC_RETICLE_URL; restart the dev server after changing these settings. readPairingToken(), discoverDaemonUrl() and knowsAllowedDevOrigins() are also exported at runtime. They are not declared in index.d.ts, so TypeScript will not see them.

`./loader`

declare function reticleNextLoader(this: unknown, source: string, inputMap?: unknown): void;
export = reticleNextLoader;

An async webpack loader. It skips anything that is not .jsx, .tsx or a .js file containing JSX, 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.

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.

What it does not do

It does not inject connect(). On Next you call it once, in a client component that your root layout renders. reticle init writes this component for you at app/reticle-dev.tsx (or src/app/reticle-dev.tsx). To write it by hand:

'use client';
import { useEffect } from 'react';

export function ReticleDev() {
  useEffect(() => {
    if (process.env.NODE_ENV !== 'development') return;
    void import('@reticlehq/react').then(({ reticle, install }) => {
      install();
      // withReticle() in next.config sets these. The bridge refuses a connect without the token.
      const token = process.env.NEXT_PUBLIC_RETICLE_TOKEN;
      const url = process.env.NEXT_PUBLIC_RETICLE_URL;
      const root = process.env.NEXT_PUBLIC_RETICLE_ROOT;
      const sdkVersion = process.env.NEXT_PUBLIC_RETICLE_SDK_VERSION;
      reticle.connect({
        ...(url ? { url } : {}),
        ...(token ? { token } : {}),
        ...(root ? { root } : {}),
        ...(sdkVersion ? { sdkVersion } : {}),
      });
    });
  }, []);
  return null;
}

NEXT_PUBLIC_RETICLE_TOKEN is empty when the daemon has not yet written ~/.reticle/pairing-token. Start the daemon, then restart next dev.

Framework by framework

What each supported stack needs, and what it gets for free.

Tools

Beyond the loop

CLI commands

Packages

Grammar

Long form

@reticlehq/next

Why it exists

Install and use

Exports

`.`

`./loader`

What it does not do

Framework by framework

​Why it exists

​Install and use

​Exports

​.

​./loader

​What it does not do

Framework by framework

Why it exists

Install and use

Exports

`.`

`./loader`

What it does not do