CSS Watch

Runtime CSS conflict detector for development - analyzes CSS conflicts, overrides, and complexity at runtime.

Overview

CSS Watch is a development tool that runs at runtime in dev mode and shows where CSS rules neutralize, override, or unnecessarily complicate each other. It's not a linter or formatter - it generates hints, not errors, and is fully disableable.

Features

• ✅ Automatic detection of duplicate classes - Find classes defined multiple times
• ✅ Analysis of CSS overrides - See which rules win and which are overridden
• ✅ Complexity evaluation - Identify selectors with high depth and DOM dependency
• ✅ DOM integration - Distinguish between active and potential conflicts
• ✅ Visual highlighting - Highlight affected elements in the DOM
• ✅ Filtering - Filter by class, selector, or file
• ✅ Source map support - Works with SCSS source maps
• ✅ Automatic updates - Updates on DOM changes

Installation

npm install css-watch --save-dev

Usage

Basic Usage

CSS Watch automatically initializes in development mode:

// In your main entry file (e.g., main.jsx)
import 'css-watch';

// That's it! CSS Watch will automatically activate in dev mode

Manual Initialization

For more control, you can manually initialize:

import { initCSSWatch } from 'css-watch';

// Initialize with options
const cssWatch = initCSSWatch({
  rootElement: 'body',  // or a specific element
  autoStart: true       // automatically start analysis
});

// Later, you can destroy it
cssWatch.destroy();

With Vite

CSS Watch works seamlessly with Vite projects. Just import it in your main file:

// src/main.jsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.jsx';

// Import CSS Watch (only active in dev mode)
if (import.meta.env.DEV) {
  import('css-watch');
}

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Three Analysis Levels

1. Structure (What exists?)

Captures which classes exist, how often they are defined, where they are defined, and in what context (global, component, utility).

Example:

• Class .button is defined in styles/global.scss and components/Button.scss
• Shows all definitions with file locations and line numbers

2. Effect (What wins?)

Examines which rules set the same property and which rule is actually applied based on CSS specificity.

Example:

• .button { color: red; } and .button.primary { color: blue; }
• Shows that .button.primary wins due to higher specificity

3. Complexity (How complicated is it?)

Evaluates selector depth, number of combined classes, use of IDs, and dependency on DOM structure.

Example:

• .container .header .title has depth 2 and is DOM-dependent
• Flags selectors that are hard to maintain

API

initCSSWatch(options?)

Initializes CSS Watch in the current application.

Parameters:

• options.rootElement (string | HTMLElement): Root element or selector (default: 'body')
• options.autoStart (boolean): Automatically start analysis (default: true)

Returns:

• Object with destroy() method to remove CSS Watch

isCSSWatchAvailable()

Checks if CSS Watch is available (dev mode).

Returns:

• boolean - true if in development mode

analyzeStyles()

Manually trigger CSS analysis.

Returns:

• Promise<AnalysisResults> - Analysis results object

Configuration

CSS Watch automatically detects development mode using:

• import.meta.env.DEV (Vite)
• process.env.NODE_ENV === 'development' (Other bundlers)

Requirements

• React 18+
• Modern browser with ES6+ support
• Development environment (automatically disabled in production)

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)

Development

# Install dependencies
npm install

# Run dev server
npm run dev

# Build library
npm run build:lib

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.