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

``bash
npm install css-watch --save-dev
`

Usage

$3

CSS Watch automatically initializes in development mode:

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

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

$3

For more control, you can manually initialize:

`javascript
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();
`

$3

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

`javascript
// 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(



);
`

Three Analysis Levels

$3

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

$3

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

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

$3

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

$3

Checks if CSS Watch is available (dev mode).

Returns:
- boolean - true if in development mode

$3

Manually trigger CSS analysis.

Returns:
- Promise - 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

`bash


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.