unplugin-transform-class

0.7.0 verified Mon Apr 27 auth: no javascript

A build tool plugin for transforming HTML class selectors according to custom rules, supporting Vite, Rollup, Webpack, esbuild, and Farm. Version 0.7.0 is current. It primarily targets developers using atomic CSS frameworks (like UnoCSS) in environments that restrict certain characters in class names (e.g., WeChat Mini Programs). Key differentiators: unplugin-based architecture for multi-bundler support, built-in default transformation rules, and utility functions for custom selector processing. Release cadence is irregular; last update 2023. Compared to similar tools, it offers broader bundler support and simpler rule configuration.

Common errors

error TypeError: Cannot read properties of undefined (reading 'transform') ↓

cause Imported the plugin from the root package instead of the bundler-specific subpath.

fix

Change import to 'unplugin-transform-class/vite' (or /webpack, /rollup, etc.)

error Error: [plugin:unplugin-transform-class] Could not load plugin: unplugin-transform-class ↓

cause Missing bundler subpath or wrong bundler specified.

fix

Ensure you use the correct subpath matching your bundler (e.g., /webpack for webpack).

error Warning: The plugin 'unplugin-transform-class/vite' seems to have no effect ↓

cause Include/exclude patterns exclude all files, or rules are empty.

fix

Check include patterns (default: [/\\.jsx?$/, /\\.vue$/, /\\.vue\?vue/]) and ensure rules have entries.

Warnings

breaking The plugin must be imported from a bundler-specific subpath (e.g., /vite). Importing from the root returns undefined or an incorrect module. ↓

fix Use correct subpath: 'unplugin-transform-class/vite', 'unplugin-transform-class/webpack', etc.

gotcha Default rules include transformations for characters like '.' -> '_dl_' which may conflict with existing CSS class naming conventions. ↓

fix Inspect default rules in Options interface; override 'rules' if unwanted transformations occur.

deprecated The plugin is not actively maintained; last update was in 2023. Compatibility with newer bundler versions is uncertain. ↓

fix Test with your specific bundler version. Consider forking or switching to actively maintained alternatives if issues arise.

gotcha The 'transformCode' utility function expects a string and rules object; it does not handle Vue/JSX parsing internally. ↓

fix Only use transformCode for raw HTML strings; for Vue/JSX use the plugin directly.

Install

npm install unplugin-transform-class

yarn add unplugin-transform-class

pnpm add unplugin-transform-class

Imports

transformClass (default)
wrong
```
import transformClass from 'unplugin-transform-class'
```
correct
```
import transformClass from 'unplugin-transform-class/vite'
```
Must import from a specific bundler subpath (/vite, /webpack, /rollup, /esbuild, /farm). The root package does not export a default plugin.

transformClass (CJS)

wrong

const transformClass = require('unplugin-transform-class')

correct

const transformClass = require('unplugin-transform-class/webpack')

For Webpack (CJS projects), use require with the /webpack subpath. Similarly for other bundlers.

Utils (named exports)

import { defaultRules, escapeRegExp, restoreSelector, transformCode, transformEscapESelector, transformSelector } from 'unplugin-transform-class/utils'

Utility functions for custom transformations; not available from bundler subpaths. Import from /utils.

Quickstart

Shows Vite plugin configuration with custom rules, include/exclude patterns, and TypeScript usage.

// vite.config.ts
import { defineConfig } from 'vite'
import transformClass from 'unplugin-transform-class/vite'

export default defineConfig({
  plugins: [
    transformClass({
      rules: {
        '/': '-s-',
        ':': '-c-',
        '[': '-fl-',
        ']': '-fr-',
      },
      include: [/\\.vue$/, /\\.vue\?vue/],
      exclude: [/[\\/]node_modules[\\/]/, /[\\/]\\.git[\\/]/],
    }),
  ],
})