A CLI tool that searches inside class and className attributes and matches against each class name individually.
npm install classname-searchA 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.
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.
| Subcommand | Description |
| ---------- | ---------------------------------- |
| stats | Count matched class names per file |
| search | Search for class names |
| replace | Search and replace class names |
| remove | Remove class names |
``bash`
npx classname-search
| Argument | Description |
| --------------- | ---------------------------------------------------------------------------------- |
| | Glob pattern for target files (fast-glob syntax). Quote to prevent shell expansion |
| | Regex pattern to match classes. Quote to prevent shell interpretation |
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.
- Supported attributes: Only class and className attributes are targeted.class
- One attribute per line: If a line contains multiple or className attributes, only the first one is processed.className={...}
- 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., ) 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.
---
Count matched class names per file.
`bash`
npx classname-search stats '
Arguments/Options:
| Argument/Option | Description |
| --------------- | ---------------------------------------------------- |
| -v, --verbose | Show detailed output including files with no matches |
Command:
`bash`
npx classname-search stats 'src/components/*/.jsx' 'text-'
Output:
`text
src/components/Header.jsx: 3 matches
src/components/Main.jsx: 4 matches
Total: 7 matches in 2 files
`
---
Command:
`bash`
npx classname-search stats --verbose 'src/components/*/.jsx' 'text-'
Output:
`text
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 for class names.
`bash`
npx classname-search search '
Arguments/Options:
| Argument/Option | Description |
| --------------------- | ---------------------------------- |
| -o, --output | 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 |
Command:
`bash`
npx classname-search search 'src/components/*/.jsx' 'flex'
Output:
`jsonl`
{"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:
`bash`
npx classname-search search 'src/components/*/.jsx' '^flex$'
Output:
`jsonl`
{"file":"src/components/Header.jsx","line":3,"matched":"flex","className":"flex","classValue":"flex flex-col"}
---
Command:
`bash`
npx classname-search search 'src/components/*/.jsx' '^items-.+'
Output:
`jsonl`
{"file":"src/components/Header.jsx","line":5,"matched":"items-start","className":"items-start","classValue":"items-start"}
---
Command:
`bash`
npx classname-search search 'src/components/*/.jsx' '^gap-\[.+\]$'
Output:
`jsonl`
{"file":"src/components/Header.jsx","line":6,"matched":"gap-[10px]","className":"gap-[10px]","classValue":"gap-[10px]"}
Search and replace class names.
`bash`
npx classname-search replace '
Arguments/Options:
| Argument/Option | Description |
| --------------- | -------------------------------------- |
| | 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:
`text`
Replaced
Basic usage:
`bash`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:
`bashMigrate 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'
remove
Remove class names.
bash
npx classname-search remove '' ''
`> [!NOTE]
> This command is equivalent to
.
> Extra whitespace is automatically removed to maintain single-space separation.Output:
`text
Removed matches of "" in files.
`$3
bash
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+'
``