@deploya/marker-plugin

A Vite plugin that automatically adds debugging and tracking attributes to JSX/TSX components during development.

Overview

The Deploya Marker Plugin is a Vite plugin that enhances React/JSX development by automatically injecting tracking attributes into your components. It adds unique identifiers and source file paths to JSX elements, making it easier to debug, track, and analyze component behavior during development.

Features

• 🎯 Automatic Attribute Injection: Adds d-id and d-sf attributes to JSX elements
• 📁 Source File Tracking: Tracks which file each element comes from
• 🔧 Development Server Integration: Provides middleware to serve raw (untransformed) code
• ⚡ Vite Integration: Seamlessly integrates with Vite's transform pipeline
• 🎨 JSX/TSX Support: Works with .jsx, .tsx, .cjsx, .mjsx, .ctsx, and .mtsx files

Installation

npm install @deploya/marker-plugin

Or with your preferred package manager:

# yarn
yarn add @deploya/marker-plugin

# pnpm
pnpm add @deploya/marker-plugin

# bun
bun add @deploya/marker-plugin

Usage

Add the plugin to your vite.config.js or vite.config.ts:

import { defineConfig } from 'vite'
import { markerPlugin } from '@deploya/marker-plugin'

export default defineConfig({
  plugins: [
    markerPlugin(),
    // ... other plugins
  ],
})

How It Works

The plugin automatically transforms your JSX/TSX code by adding two attributes to each JSX element:

• d-id: A unique random identifier for the element
• d-sf: The source file path relative to your project root

Example Transformation

Before (your source code):

function MyComponent() {
  return (
    <div>
      <h1>Hello World</h1>
      <button onClick={handleClick}>Click me</button>
    </div>
  )
}

After (transformed by the plugin):

function MyComponent() {
  return (
    <div d-id="abc123def456" d-sf="/src/components/MyComponent.jsx">
      <h1 d-id="ghi789jkl012" d-sf="/src/components/MyComponent.jsx">Hello World</h1>
      <button d-id="mno345pqr678" d-sf="/src/components/MyComponent.jsx" onClick={handleClick}>Click me</button>
    </div>
  )
}

Development Server Middleware

The plugin also provides a development server middleware that serves the original (untransformed) source code at the /__tagger_raw/ endpoint. This can be useful for debugging or analysis tools that need access to the original source.

For example:

• Original file: /src/components/MyComponent.jsx
• Raw source available at: http://localhost:5173/__tagger_raw/src/components/MyComponent.jsx

API

markerPlugin()

Creates and returns a Vite plugin instance.

Returns: Plugin - A Vite plugin object

Example:

import { markerPlugin } from '@deploya/marker-plugin'

const plugin = markerPlugin()

Requirements

• Vite: ^7.0.0
• Node.js: Compatible with ES2022+

Development

Setup

1. Clone the repository
2. Install dependencies:

   npm install

Available Scripts

• npm run build - Build the plugin for production
• npm run clean - Remove the dist directory
• npm run format - Format code using Biome
• npm run lint - Lint code using Biome

Building

npm run build

This creates the distribution files in the dist/ directory.

Technical Details

• Transform Phase: The plugin runs in the pre enforce phase of Vite's transform pipeline
• File Detection: Uses regex pattern /\.([cm]?(j|t)sx)$/ to identify JSX/TSX files
• Element Detection: Uses regex pattern /<([A-Za-z][A-Za-z0-9]*)\b(?![^>]*d-sf)/g to find elements without existing d-sf attributes
• Code Transformation: Uses magic-string for efficient code modifications
• ID Generation: Generates random IDs using Math.random().toString(36).substring(2, 15)

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes
4. Run tests and linting: npm run lint
5. Build the project: npm run build
6. Commit your changes: git commit -am 'Add some feature'
7. Push to the branch: git push origin feature/your-feature
8. Submit a pull request

License

UNLICENSED - This is proprietary software.

Author

Martin Jakobsson
Email: [email protected]

This plugin is part of the Deploya ecosystem for enhanced development tooling.