Vite Plugin Class Blacklist

A Vite plugin that scans your generated CSS bundles for specific blacklisted class names and issues warnings or errors.

Use Cases

This plugin is useful for:

• Avoid Class Conflicts: Prevent the usage of utility classes that deviate from other already defined classes.
• Migration Safety: When migrating away from a CSS framework or a set of legacy classes, ensure that no new usages of these classes slip into the codebase.
• Sanity Checks: Ensure that temporary debugging classes (like .debug-border) are not accidentally shipped to production.

Installation

pnpm add -D vite-plugin-class-blacklist
# or
npm install -D vite-plugin-class-blacklist
# or
yarn add -D vite-plugin-class-blacklist

Usage

Add the plugin to your vite.config.ts:

import { defineConfig } from 'vite';
import classBlacklistPlugin from 'vite-plugin-class-blacklist';

export default defineConfig({
  plugins: [
    classBlacklistPlugin({
      blacklist: ['fixed', 'absolute', 'debug-red'],
      mode: 'warn', // or 'error'
    }),
  ],
});

Configuration

The plugin accepts an options object with the following properties:

Option	Type	Description
blacklist	string[]	An array of class names (strings) to search for in the CSS bundle.
mode	'warn' | 'error'	Defines the behavior when a blacklisted class is found. 'warn' will log a warning to the console, while 'error' will throw an error and fail the build.

License

MIT