https://github.com/teplostanski/vite-plugin-readable-classnames
💅 Make your scoped CSS modules class names clear, consistent and readable by automatically adding component names — a better alternative to the default Vite behavior
https://github.com/teplostanski/vite-plugin-readable-classnames
css less plugin react scss tsdown vite vite-plugin vue
Last synced: about 1 year ago
JSON representation
💅 Make your scoped CSS modules class names clear, consistent and readable by automatically adding component names — a better alternative to the default Vite behavior
- Host: GitHub
- URL: https://github.com/teplostanski/vite-plugin-readable-classnames
- Owner: teplostanski
- License: mit
- Created: 2024-04-27T20:29:59.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-05-11T18:51:29.000Z (about 1 year ago)
- Last Synced: 2025-05-11T19:38:24.236Z (about 1 year ago)
- Topics: css, less, plugin, react, scss, tsdown, vite, vite-plugin, vue
- Language: TypeScript
- Homepage: https://vite-plugin-readable-classnames.teplostanski.dev/
- Size: 1000 KB
- Stars: 23
- Watchers: 1
- Forks: 2
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
English | [Russian](./README.ru.md)
vite-plugin-readable-classnames
[
](https://npmjs.com/package/vite-plugin-readable-classnames)
[
](https://npmjs.com/package/vite-plugin-readable-classnames)
[
](https://npmjs.com/package/vite-plugin-readable-classnames)
[
](https://npmjs.com/package/vite-plugin-readable-classnames)
[
](https://github.com/teplostanski/vite-plugin-readable-classnames)
[
](https://codecov.io/gh/teplostanski/vite-plugin-readable-classnames)
Make your scoped CSS module class names clear and readable — this plugin automatically adds the module filename and other useful info to class names for easier development.
Included in the Awesome Vite.js list 
## 📦 Installation
[npmjs.com](https://npmjs.com/package/vite-plugin-readable-classnames) • [yarnpkg.com](https://yarnpkg.com/package?q=vite-plugin-readable-classnames&name=vite-plugin-readable-classnames)
```bash
npm install -D vite-plugin-readable-classnames
yarn add -D vite-plugin-readable-classnames
pnpm add -D vite-plugin-readable-classnames
bun add -d vite-plugin-readable-classnames
```
## Migration from vite-plugin-pretty-module-classnames
`vite-plugin-readable-classnames` is the new identity for `vite-plugin-pretty-module-classnames`. This guide will help you migrate from `vite-plugin-pretty-module-classnames` to `vite-plugin-readable-classnames`.
1. Uninstall the old plugin and install the new one
```sh [npm]
npm uninstall vite-plugin-pretty-module-classnames
npm install -D vite-plugin-readable-classnames
```
2. Update the import and plugin usage in your `vite.config.js` or `vite.config.ts`
```diff
- import prettyModuleClassnames from 'vite-plugin-pretty-module-classnames'
+ import readableClassnames from 'vite-plugin-readable-classnames'
export default defineConfig {
- plugins: [prettyModuleClassnames()]
+ plugins: [readableClassnames()]
}
```
## 🦾 Features
- Framework-agnostic:
- Tested on projects with   
- Potentially works with any framework. If you have any problems, write to the [Issue](https://github.com/teplostanski/vite-plugin-readable-classnames/issues)
- Universal:
- Compatible with both `CommonJS` and `ES Modules`
- Support `Vite 2.x`
- Customizable: Flexible configuration through options object
## 🤔 What Problem Does This Plugin Solve?
In React with CSS modules, we're used to class names like `SomeComponent__classname_hash`. By default, Vite generates names in the format `__classname_hash`, omitting the component name, which makes debugging more difficult.
If you try to add the component name through the `generateScopedName: '[name]__[local]_[hash:base64:5]'` configuration, React will add an extra `-module` suffix, and in Vue, such configuration may lead to build errors.
This plugin solves these problems and ensures predictable, readable class naming in the format `ComponentName__classname_hash` regardless of the framework.
> [!TIP]
> **What are generated class names and where are they visible?**
>
> When you use CSS modules, the resulting class names are automatically generated by the bundler (e.g., Vite or Webpack). These names are visible:
> - in the HTML code of the page (through browser DevTools);
> - in the final CSS file;
> - when debugging in the browser as you search for the right element or style.
>
> Readable class names that include the component name help you quickly understand where a style comes from, making debugging and project maintenance easier.
## ⚙️ Usege
###### Example
```js
// vite.config.js
// ...
import readableClassnames from 'vite-plugin-readable-classnames'
export default defineConfig({
plugins: [readableClassnames()],
})
```
## 📚 Documentation
For full documentation, visit [vite-plugin-readable-classnames.teplostanski.dev](https://vite-plugin-readable-classnames.teplostanski.dev) [ EN | RU ].
## 🤝 Contributing
Want to contribute? Awesome! To show your support is to star the project, or to raise [issues on GitHub](https://github.com/teplostanski/vite-plugin-readable-classnames/issues).
Before you contribute to the development of the project, read the [rules](https://github.com/teplostanski/vite-plugin-readable-classnames/blob/main/CONTRIBUTING.md).
Thanks again for your support, it is much appreciated! 🙏
© License
MIT License © 2024-2025 teplostanski
❤ Fund this project
donate.teplostanski.dev