Quan ERP Vite CSS Scoping Plugin

A PostCSS plugin designed to implement strict visual isolation for Quan ERP frontend modules. It automatically encapsulates CSS selectors within a unique plugin-specific attribute to prevent style leakage in the shared ERP shell.

🛡️ Isolation Strategy

In a modular micro-frontend environment, CSS selector collisions are a common risk. This plugin solves this by rewriting all CSS selectors to be scoped to a parent attribute.

Attribute Scoping

Every selector in your plugin's CSS is prepended with [data-plugin="your-plugin-name"].

• Source: .my-button { color: red; }
• Compiled: [data-plugin="xxx"] .my-button, [data-plugin="xxx"].my-button { color: red; }

Global Normalization

The plugin automatically converts global-scope selectors like :root and :host into the plugin-scoped attribute. This allows each plugin to define its own CSS variables without polluting the global document space.

🛠️ API Reference

quanERPCssPlugin(metadata, options)

| Argument | Type | Description | | :--- | :--- | :--- | | metadata.name | string | The unique identifier of the plugin (used for the attribute value). | | options.ignoreFiles | string[] | List of file paths to exclude from scoping (e.g., third-party libraries). |

🚀 Integration Guide

Vite Configuration

To use this plugin in a Vite-based project, add it to your vite.config.ts:

import quanERPCssPlugin from '@quan-erp/vite-css-plugins';

export default defineConfig({
    css: {
        postcss: {
            plugins: [
                quanERPCssPlugin({ name: 'my-plugin-name' })
            ]
        }
    }
});

⚙️ Technical Behavior

• Dual Scoping: The plugin generates both descendant ([data-plugin] .child) and self-scoped ([data-plugin].self) selectors to ensure styles apply correctly regardless of where the class is placed on the plugin root.
• Animation Safety: Rules inside @keyframes are automatically ignored to preserve native browser animation behavior.
• Recursive Protection: The plugin detects if a selector is already scoped to prevent double-prefixing during incremental builds.

[!TIP] Use the ignoreFiles option if you are importing global design system styles that should not be scoped to your specific plugin.