Detect and remove unused CSS module classes
npm install check-unused-cssA zero-config tool to find unused CSS classes and non-existent class references in your TypeScript project. Works with .module.css, .module.scss, and .module.sass.
No more dead styles in your codebase!
Fully tested - check the tests folder for real-world scenarios.
``bash`
npm i --D check-unused-css
Add script to package.json:
`json`
{
"scripts": {
"check-unused-css": "check-unused-css"
}
}
Run:
`bash`
npm run check-unused-css
You can specify a custom folder path to check:
`bash`
npx check-unused-css src/components
By default, it checks the src directory.
#### Exclude patterns
You can exclude certain files or directories from being checked using the --exclude or -e flag. Patterns are relative to your project root:
`bashExclude specific directories
npx check-unused-css --exclude "src/components/SidePanel/**"
npx check-unused-css --exclude "./src/stories/**"
Exclude patterns support both specific paths and glob syntax:
Specific paths (from project root):
-
- exclude specific component folder
- ./src/stories/** - exclude stories directory
- src/legacy/** - exclude legacy codeGlob patterns (universal matching):
-
/test/, /__tests__/ - test directories anywhere
- /stories/ - story files anywhere
- /.test.{css,scss}, /.spec.* - test files by pattern
- /node_modules/ - node modules (usually not needed)Note: Remember to wrap patterns in quotes to prevent shell expansion
#### Strict mode for dynamic class access
By default, the tool shows warnings for dynamic class access but doesn't fail the process. Use the
--no-dynamic flag to treat dynamic class usage as errors:`bash
Fail on dynamic class access
npx check-unused-css --no-dynamicCombine with other options
npx check-unused-css src/components --no-dynamic --exclude "/test/"
`When
is used:
- Dynamic class access (e.g., styles[variable]) will be treated as errors instead of warnings
- The process will exit with code 1 if any dynamic usage is detected
- Error messages will be displayed in red instead of yellow warningsThis is useful in CI/CD pipelines where you want to enforce explicit class usage.
Read more about why dynamic class access should be avoided
#### Ignoring files or lines with comments
You can ignore specific lines or entire files from CSS checking using special comments, similar to ESLint:
For CSS files:
`css
/ check-unused-css-disable /
.unusedClass { }
`css
.usedClass { }/ check-unused-css-disable-next-line /
.unusedClass { }
`For TypeScript/TSX files:
tsx
// check-unused-css-disable
import styles from './Component.module.css';export const Component = () => (
);
`tsx
import styles from './Component.module.css';export const Component = () => (
{/ check-unused-css-disable-next-line /}
);
`Supported comment formats:
-
- ignore entire CSS file
- / check-unused-css-disable-next-line / - ignore next line in CSS
- // check-unused-css-disable - ignore entire TS/TSX file
- // check-unused-css-disable-next-line - ignore next line in TS/TSX
- {/ check-unused-css-disable-next-line /} - ignore next line in JSX (TSX)TypeScript Path Aliases Support
check-unused-css automatically supports TypeScript path aliases defined in your tsconfig.json.$3
If you have path aliases in your TypeScript configuration:
`json
// tsconfig.json
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/": ["src/"],
"@components/": ["src/components/"],
"~/": ["lib/"]
}
}
}
`Then imports using these aliases will be correctly resolved:
typescript
// Component.tsx
import styles from '@/components/Button.module.css'; // ✅ Works
import styles from '@components/ui/Card.module.css'; // ✅ Works
import styles from '~/shared/theme.module.css'; // ✅ Works
`$3
- Automatically finds and parses
in your project
- Supports extends for shared configurations
- Supports wildcard patterns (*)
- Falls back to regular path resolution if no aliases match
- No configuration needed - it just works!$3
- ✅ Simple aliases:
"@utils": ["src/utils"]
- ✅ Wildcard aliases:
- ✅ Nested aliases:
- ✅ Multiple path mappings (uses first match)
- ✅ Config inheritance via
- ✅ Project references (automatically resolves paths from referenced tsconfig files)CI Integration
Set up automated checks for unused CSS in your pipeline.
See CI integration examples for GitHub Actions and GitLab CI.
Limitations
The tool only works when CSS classes are used directly, for example:
tsx
import styles from './Component.module.css';// ...
`Dynamic class access cannot be detected:
tsx
import styles from './Component.module.css';const dynamicClass = Math.random() * 10 >= 5 ? 'classOne' : 'classTwo';
// ...
// cannot detect usage
`In such cases, the tool will skip the check and mark it as passed. Avoid dynamic access and use explicit class names for clarity.
FAQ
$3
First, it doesn't work in CI without generating files.
Second, even in IDEs it often doesn't work reliably due to caching, misconfigured TypeScript, or not using the workspace version.---
$3
In that case, this library is probably not a good fit for your project.
I recommend not mixing concerns. Instead, you can:
- write explicit map functions to convert values to class names
- use class-variance-authority---
$3
If you like Tailwind - go for it!---
$3
These libs require:
- generating and committing files to your repo
- developing in watch mode to keep them up to date check-unused-css works out of the box, supports .css, .scss, .sass`, and requires zero config.MIT