@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

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): 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

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.

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 yourself, once, in a client component:

'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;
}

Framework by framework

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