npm package: @ryanclark/swc-plugin-jsx-marker
Description: SWC plugin for adding attributes to design system components
Author: Ryan Clark
Latest version: 1.0.0

# 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

```bash
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:

```ts
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:

```tsx
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:

```tsx
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             |