@lxgicstudios/dead-css

Find unused CSS selectors by cross-referencing your stylesheets against HTML, JSX, TSX, and other source files. Report dead selectors with exact file locations. Auto-remove dead code with --remove.

Dead CSS is wasted bandwidth. This tool finds it and (optionally) kills it.

Install

# Use directly with npx
npx @lxgicstudios/dead-css

# Or install globally
npm install -g @lxgicstudios/dead-css

Usage

# Scan current directory
dead-css

# Specify CSS and source paths
dead-css --css ./public/styles --src ./src

# Auto-remove dead selectors (creates .bak backups)
dead-css --css styles.css --src ./src --remove

# Ignore dynamic class patterns
dead-css --ignore "js-*" --ignore "is-*" --ignore "has-*"

# JSON output for scripting
dead-css --json

How It Works

1. Parses all CSS files and extracts every selector
2. Scans your source files (HTML, JSX, TSX, Vue, Svelte, etc.) for class names, IDs, and tag references
3. Cross-references selectors against what's actually used
4. Reports unused selectors with file and line numbers

It's not perfect for highly dynamic class names (like className={'btn-' + variant}), but it catches the vast majority of dead CSS in real projects. Use --ignore patterns for known dynamic prefixes.

Options

Option	Description	Default
--css <path>	CSS files or directory to scan	.
--src <path>	Source files to check against	.
--remove	Remove dead selectors (creates .bak backup)	false
--ignore <pat>	Ignore selectors matching glob pattern	-
--ext <exts>	Source file extensions (comma-separated)	html,jsx,tsx,js,ts,vue,svelte
--json	Output results as JSON	false
--help	Show help message	-

Features

• Zero external dependencies
• Scans HTML, JSX, TSX, Vue, Svelte, PHP, ERB files
• Detects class names from class, className, template literals, and classList APIs
• Reports exact file locations and line numbers
• Auto-remove with --remove (always creates backups)
• Ignore patterns for dynamic/JS-toggled classes
• JSON output for CI pipelines

Supported Source Patterns

The tool detects class/ID usage from these patterns:

• class="my-class" and className="my-class"
• className={'my-class'} and template literal classes
• classList.add('my-class'), .toggle(), .contains()
• id="my-id"
• HTML tag names (<div>, <section>, etc.)
• Data attribute selectors

---

Built by LXGIC Studios

GitHub | Twitter