English • Russian

vite-plugin-readable-classnames

docs · github · codeberg · npm · yarn · fund this package

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

🪞 Mirror Repo

Here!

📦 Installation

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

🦾 Features

• Framework-agnostic:
  • Tested on projects with
  • Potentially works with any framework. If you have any problems, write to the Issue
• Universal:
  • Compatible with both CommonJS and ES Modules
  • Support Vite 2.x
• Customizable: Flexible configuration through options object

🤔 Problem

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.

📚 Documentation

For full documentation, visit vite-plugin-readable-classnames.js.org.

⚙️ Usage

import readableClassnames from 'vite-plugin-readable-classnames'

export default defineConfig({
  plugins: [
    readableClassnames()
  ]
})

Options

lineNumber

The lineNumber option adds the line number where the class is declared in the source file to the class name.

import readableClassnames from 'vite-plugin-readable-classnames'

export default defineConfig({
  plugins: [readableClassnames({ lineNumber: true })],
})

If your CSS file looks like this:

1 .wrapper {
2   /* styles */
3 }
4
5 .container {
6   /* styles */
7 }

The resulting class names will be:

• SomeComponent__wrapper_abcd1-1
• SomeComponent__container_abcd2-5

[!IMPORTANT] Please note: The lineNumber option works the same way as Vite's standard class name generation when using preprocessors (Sass, Less, Stylus). The line number is taken from the generated CSS, where empty lines and comments are usually removed. Therefore, the line numbers in class names may not match the line numbers in the source files.

In .vue files, line counting always starts from the <style module> tag, regardless of where it is located in the file. So the line number in the class name will be counted from the beginning of the <style module> block, not from the beginning of the entire file.

separator

The separator option allows you to customize the characters used to join parts of the generated class name.
You can override any of the following fields (all are optional, default values are shown below):

Field	Default	Description
beforeHash	'_'	Separator before the hash part
beforeClassName	'__'	Separator between the file name and class name
beforeLineNumber	'-'	Separator before the line number (if enabled)

import readableClassnames from 'vite-plugin-readable-classnames'

export default defineConfig({
  plugins: [
    readableClassnames({
      separator: {
        beforeClassName: '--', // Uses double dash instead of double underscore
      }
    })
  ]
})

In this case, class names will look like: SomeComponent--classname_abcd1

Tip

You can specify only the fields you want to override; the rest will use the default values.

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

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

- import prettyModuleClassnames from 'vite-plugin-pretty-module-classnames'
+ import readableClassnames from 'vite-plugin-readable-classnames'

export default defineConfig {
-  plugins: [prettyModuleClassnames()]
+  plugins: [readableClassnames()]
}

🤝 Contributing

Want to contribute? Awesome! To show your support is to star the project, or to raise issues on GitHub.

Before you contribute to the development of the project, read the rules.

Thanks again for your support, it is much appreciated! 🙏

© License

MIT License © 2024-present teplostanski