@styleui/next-plugin

The official Next.js integration plugin for StyleUI.

@styleui/next-plugin acts as a compilation-time bridge for StyleUI. It wraps your Next.js configuration to automatically inject a custom Babel plugin (babel-plugin-styleui) during development mode. This plugin tags your React elements with source-code location metadata, allowing the StyleUI browser extension to map visual elements on your screen directly to the corresponding source file and line number in your editor.

Installation

This package is typically installed and configured automatically when you run the StyleUI setup CLI:

npx styleui init

If you prefer to install it manually:

npm install -D @styleui/next-plugin

How It Works

1. Development Environment Restriction: The plugin enforces that AST transformation and asset decoration ONLY occur in development mode (process.env.NODE_ENV === 'development'). In production builds, it acts as a pass-through, introducing zero runtime or bundle size overhead.
2. Webpack and Turbopack Support: It integrates seamlessly with both standard Webpack compilation and Next.js Turbopack modes (with automatic Next.js 14/15/16 version checks to apply appropriate configuration structure).
3. AST Metadata Decoration: It runs a custom Babel plugin targeting files under your source directories (src/, app/, pages/, components/). It excludes node_modules and .next folders to ensure fast compilation.
4. Attribute Injection: It decorates elements with the following attributes:
   • data-tail-file: The absolute path to the local file containing the element.
   • data-tail-line: The source line number where the element's JSX definition starts.

Usage

Wrap your existing Next.js configuration using the withStyleUI helper function.

CommonJS (next.config.js or next.config.cjs)

const { withStyleUI } = require('@styleui/next-plugin');

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  // Your other Next.js configurations
};

module.exports = withStyleUI(nextConfig);

ESM (next.config.mjs or next.config.js with "type": "module")

import { withStyleUI } from '@styleui/next-plugin';

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  // Your other Next.js configurations
};

export default withStyleUI(nextConfig);

TypeScript (next.config.ts)

import { withStyleUI } from '@styleui/next-plugin';
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  reactStrictMode: true,
  // Your other Next.js configurations
};

export default withStyleUI(nextConfig);

Troubleshooting

Webpack/Babel Loader Warnings

If you receive loader resolution issues, ensure that your packages are fully installed using npm install or your package manager's equivalent.

For monorepos, make sure @styleui/next-plugin is listed under the target app's devDependencies or is properly hoisted.