locatorjs-nextjs-experimental

⚠️ EXPERIMENTAL: This is an experimental package for adding LocatorJS support to Next.js 13+ with App Router and Turbopack.

A Next.js plugin that adds data-source attributes to all JSX elements for debugging with LocatorJS. Works with both webpack and Turbopack bundlers.

Installation

npm install locatorjs-nextjs-experimental --save-dev

Usage

Basic Setup

// next.config.js
const locatorJSPlugin = require('locatorjs-nextjs-experimental');

const nextConfig = {
  reactStrictMode: true,
  // Your existing config...
  ...locatorJSPlugin(), // Spread the plugin config
};

module.exports = nextConfig;

With Options

// next.config.js
const locatorJSPlugin = require('locatorjs-nextjs-experimental');

const nextConfig = {
  // Your existing config...
  ...locatorJSPlugin({
    enabled: process.env.ENABLE_LOCATOR === 'true',
    exclude: /(node_modules|\.test\.(tsx?|jsx?))$/,
    test: /\.(tsx|jsx)$/, // Only JSX/TSX files
  }),
};

module.exports = nextConfig;

Turbopack Only

// next.config.js
const locatorJSPlugin = require('locatorjs-nextjs-experimental');

const nextConfig = {
  turbopack: {
    rules: locatorJSPlugin.turbopack(),
  },
};

module.exports = nextConfig;

What It Does

This plugin adds data-source attributes to all JSX elements at build time:

// Input
<div>
  <h1>Hello</h1>
</div>

// Output (in DOM)
<div data-source="/path/to/file.tsx:1:1">
  <h1 data-source="/path/to/file.tsx:2:3">Hello</h1>
</div>

The format is: <fullPath>:<line>:<column>

Requirements

• Next.js 13+ (App Router supported)
• Works with both webpack and Turbopack
• Requires LocatorJS browser extension or runtime library

Browser Extension

Install the LocatorJS browser extension to use with this plugin:

• Chrome Extension

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | bundler | 'webpack' \| 'turbopack' \| 'auto' | 'auto' | Which bundler to configure | | enabled | boolean | true in development | Enable/disable the plugin | | test | RegExp | /\.(tsx\|jsx\|ts\|js)$/ | Files to transform | | exclude | RegExp \| string | /node_modules/ | Files to exclude |

Compatibility

• ✅ Next.js 13+ with App Router
• ✅ React Server Components
• ✅ Webpack bundler
• ✅ Turbopack bundler
• ✅ TypeScript & JavaScript
• ✅ Next.js Middleware (webpack mode)
• ⚠️ Next.js Middleware (turbopack mode - known limitation)

License

MIT

Status

This is an experimental package. For production use, please wait for the official LocatorJS Next.js support.