classname-search

A CLI tool that searches inside class and className attributes and matches against each class name individually.

Important

This documentation is written primarily for AI agents.
No extra context is provided for human readers.

Why not grep?

1. Matches each class name individually

   • grep matches entire lines. This tool parses class and className attributes and matches against each class name separately, so you can target flex-col without matching flex.

2. Structured output (JSONLines)

   • The search command outputs results as JSONLines with file path, line number, matched string, and full class value—easy to parse and act on programmatically.

3. Regex replacement with capture groups

   • The replace command supports $1, $2, etc., enabling pattern-based bulk replacements (e.g., -slate-(\d+)$ → -neutral-$1) in a single command.

Subcommands

Subcommand	Description
stats	Count matched class names per file
search	Search for class names
replace	Search and replace class names
remove	Remove class names

Usage

npx classname-search <subcommand> '<target-glob>' '<class-regex>' [options]

Argument	Description
<target-glob>	Glob pattern for target files (fast-glob syntax). Quote to prevent shell expansion
<class-regex>	Regex pattern to match classes. Quote to prevent shell interpretation

⚠️ Windows CLI Issues

PowerShell environment:
To check if you're in PowerShell, run echo --%. If the output is empty, you're in PowerShell.
Always use the stop-parsing token (--%) with quotes. Without it, special characters may be silently modified, causing incorrect results without any error.
The tool automatically strips outer quotes from arguments.

cmd.exe passthrough (when not using --%):
npx may pass through cmd.exe internally on Windows, which consumes ^ as an escape character.
To check if ^ is consumed, run npx -y node -e "console.log(process.argv[1])" "^test". If the output is test instead of ^test, escape ^ as ^^ (e.g., ^flex$ → ^^flex$). Without this, results will be silently incorrect.

Limitations

• Supported attributes: Only class and className attributes are targeted.
• One attribute per line: If a line contains multiple class or className attributes, only the first one is processed.
• Multi-line attributes are ignored: Class attributes spanning multiple lines are not matched.
• Dynamic values are ignored: Only values enclosed in double or single quotes are targeted. Attributes using JSX expressions (e.g., className={...}) are skipped.
• Comments are processed: The tool does not ignore commented-out code.
• Files outside CWD are ignored: The tool only processes files within the current working directory.

---

stats

Count matched class names per file.

npx classname-search stats '<target-glob>' '<class-regex>' [options]

Arguments/Options:

Argument/Option	Description
-v, --verbose	Show detailed output including files with no matches

Examples

Command:

npx classname-search stats 'src/components/**/*.jsx' 'text-'

Output:

src/components/Header.jsx: 3 matches
src/components/Main.jsx: 4 matches

Total: 7 matches in 2 files

---

Command:

npx classname-search stats --verbose 'src/components/**/*.jsx' 'text-'

Output:

src/components/Header.jsx: 3 matches
src/components/Main.jsx: 4 matches
src/components/Footer.jsx: 0 matches

Total: 7 matches in 3 files

search

Search for class names.

npx classname-search search '<target-glob>' '<class-regex>' [options]

Arguments/Options:

Argument/Option	Description
-o, --output <file>	Output results to a JSONLines file

Output Format (JSONLines):

Each match is output as a JSON object on a separate line.

Field	Description
file	File path relative to the current working directory
line	Line number (1-based)
matched	The substring that matched the regex pattern
className	The individual class name that contains the matched string
classValue	Full value of the class attribute

Examples

Command:

npx classname-search search 'src/components/**/*.jsx' 'flex'

Output:

{"file":"src/components/Header.jsx","line":3,"matched":"flex","className":"flex","classValue":"flex flex-col"}
{"file":"src/components/Header.jsx","line":3,"matched":"flex","className":"flex-col","classValue":"flex flex-col"}
{"file":"src/components/Header.jsx","line":4,"matched":"flex","className":"inline-flex","classValue":"inline-flex"}

---

Command:

npx classname-search search 'src/components/**/*.jsx' '^flex$'

Output:

{"file":"src/components/Header.jsx","line":3,"matched":"flex","className":"flex","classValue":"flex flex-col"}

---

Command:

npx classname-search search 'src/components/**/*.jsx' '^items-.+'

Output:

{"file":"src/components/Header.jsx","line":5,"matched":"items-start","className":"items-start","classValue":"items-start"}

---

Command:

npx classname-search search 'src/components/**/*.jsx' '^gap-\[.+\]$'

Output:

{"file":"src/components/Header.jsx","line":6,"matched":"gap-[10px]","className":"gap-[10px]","classValue":"gap-[10px]"}

replace

Search and replace class names.

npx classname-search replace '<target-glob>' '<class-regex>' '<replacement>' [options]

Arguments/Options:

Argument/Option	Description
<replacement>	String to replace matched classes with

Note

When a class is replaced with an empty string, extra whitespace is automatically removed to maintain single-space separation.

Output:

Replaced <N> matches of "<class-regex>" with "<replacement>" in <N> files.

Examples

Basic usage:

# Replace "fixed" with "absolute"
npx classname-search replace 'src/components/**/*.jsx' '^fixed$' 'absolute'
# Replace "-red-100" with "-red-200"
npx classname-search replace 'src/components/**/*.jsx' -- '-red-100$' '-red-200'

Using capture groups:

# Migrate slate colors to neutral
# ✅ bg-slate-100 → bg-neutral-100
# ✅ text-slate-200 → text-neutral-200
# ❌ bg-slate-300/50
npx classname-search replace 'src/components/**/*.jsx' -- '-slate-(\d+)$' '-neutral-$1'

# Migrate blue colors to indigo
# ✅ text-blue-400 → text-indigo-400
# ✅ bg-blue-500 → bg-indigo-500
# ❌ border-blue-600
npx classname-search replace 'src/components/**/*.jsx' '(text|bg)-blue-(\d+)$' '$1-indigo-$2'

# Change breakpoint md: to lg:
# ✅ md:hidden → lg:hidden
# ✅ md:flex → lg:flex
# ❌ sm:hidden
npx classname-search replace 'src/components/**/*.jsx' '^md:(.+)$' 'lg:$1'

remove

Remove class names.

npx classname-search remove '<target-glob>' '<class-regex>'

Note

This command is equivalent to replace '<target-glob>' '<class-regex>' ''. Extra whitespace is automatically removed to maintain single-space separation.

Output:

Removed <N> matches of "<class-regex>" in <N> files.

Examples

# Remove "font-normal" class
npx classname-search remove 'src/components/**/*.jsx' '^font-normal$'

# Remove all slate color classes
npx classname-search remove 'src/components/**/*.jsx' -- '-slate-\d+'