@styleui/vite-plugin

The official Vite integration plugin for StyleUI.

@styleui/vite-plugin acts as a compilation-time bridge for StyleUI. It wraps your Vite configuration to automatically parse and transform your source code during development. It tags JSX elements with source-code location metadata, enabling the StyleUI browser extension to map visual elements on your screen directly to the corresponding source file and line number in your code 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/vite-plugin

How It Works

1. Development Transformation: The plugin parses .tsx and .jsx files using Babel parser and traverses the AST.
2. Filters & Exclusions: It automatically ignores files inside node_modules, query parameter imports, and files outside standard source directories (src/, app/, pages/, components/).
3. AST Metadata Decoration: It injects the following source-tracing data attributes into elements:
   • data-tail-file: The normalized absolute path to the local source file.
   • data-tail-line: The source line number where the element's JSX definition starts.
4. React Fragment Safety: Skips React fragments (e.g. <Fragment> or <React.Fragment>) and shorthand fragment syntax (<>...</>) to prevent invalid HTML attribute compilation.

Usage

Register the plugin in your vite.config.ts (or vite.config.js).

TypeScript (vite.config.ts)

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import withStyleUI from '@styleui/vite-plugin';

export default defineConfig({
  plugins: [
    withStyleUI(),
    react()
  ],
});

ESM (vite.config.js or vite.config.mjs)

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import withStyleUI from '@styleui/vite-plugin';

export default defineConfig({
  plugins: [
    withStyleUI(),
    react()
  ],
});

CommonJS (vite.config.cjs)

const { defineConfig } = require('vite');
const react = require('@vitejs/plugin-react');
const withStyleUI = require('@styleui/vite-plugin');

module.exports = defineConfig({
  plugins: [
    withStyleUI(),
    react()
  ],
});