@ryanclark/swc-plugin-jsx-marker

swc-plugin-jsx-marker

A simple SWC plugin that adds a data-uic attribute to JSX elements from a specified library. When using a design system library like Chakra UI, this plugin can help you identify the components in the DOM for easier debugging and testing. This works similarly to how the Emotion SWC plugin adds the name of the component to the class name. This plugin was adapted from the Emotion SWC plugin.

Installation

npm install @ryanclark/swc-plugin-jsx-marker --save-dev
pnpm add @ryanclark/swc-plugin-jsx-marker -D

Usage

Add the plugin to your SWC configuration. Here's an example using Vite with the @vitejs/plugin-react-swc plugin:

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

const config = defineConfig(({mode}) => ({
  plugins: react({
    plugins: [
      [
        '@ryanclark/swc-plugin-jsx-marker',
        {
          libraryName: '@example/design-system', // defaults to '@chakra-ui/react' if not specified
          enabled: mode !== 'production', // defaults to true if not specified
          // attributeName: 'data-testid', // defaults to 'data-uic' if not specified
        },
      ],
    ],
  }),
}));

export { config as default };

This plugin should come first in the list of plugins to ensure it runs before other transformations. It only adds the data-uic attribute to the JSX elements, so it needs to run before any other plugins that might modify the JSX.

This will transform this:

import { chakra, Box, Button, HStack } from '@chakra-ui/react';

const Item = chakra(Box)({
  baseStyle: {
    padding: '8px',
    border: '1px solid black',
  },
});

const StyledItem = styled(Item, {
  baseStyle: {
    padding: '16px',
    border: '1px solid red',
  },
});

function Example() {
  return (
    <HStack>
      <Item>
        <Button>Click me</Button>
      </Item>
      <StyledItem>
        <Button>Click me</Button>
      </StyledItem>
    </HStack>
  )
}

into:

import { chakra, Box, Button, HStack } from '@chakra-ui/react';

const Item = chakra(Box, {
  baseStyle: {
    padding: '8px',
    border: '1px solid black',
  },
});

const StyledItem = styled(Item, {
  baseStyle: {
    padding: '16px',
    border: '1px solid red',
  },
});

function Example() {
  return (
    <HStack data-uic="Example-HStack">
      <Item data-uic="Example-Item-Box">
        <Button>Click me</Button>
      </Item>
      <StyledItem data-uic="Example-StyledItem-Item">
        <Button>Click me</Button>
      </StyledItem>
    </HStack>
  )
}

Configuration Options

The plugin accepts the following configuration options:

Option	Type	Default	Description
libraryName	string	'@chakra-ui/react'	The name of the library whose components should be marked
enabled	boolean	true	Whether the plugin is enabled
attributeName	string	'data-uic'	The attribute name to add to the JSX elements