# mini-css-class-name

> Minimum size unique CSS class names generator

Latest version **0.16.0** (published 2026-01-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install mini-css-class-name
pnpm add mini-css-class-name
yarn add mini-css-class-name
bun add mini-css-class-name
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.16.0 |
| Published | 2026-01-25 |
| First published | 2019-02-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 13.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 11 |
| Author | Alexander Zaytsev |
| Maintainers | shoonia |
| Keywords | css, loader, css-loader, getLocalIdent, minify, modules, Identifiers, webpack, gatsby |

## Links

- npm: https://www.npmjs.com/package/mini-css-class-name
- Repository: https://github.com/shoonia/mini-css-class-name
- Homepage: https://github.com/shoonia/mini-css-class-name#readme
- Issues: https://github.com/shoonia/mini-css-class-name/issues
- npm.io page: https://npm.io/package/mini-css-class-name

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 0.16.0 (latest) — 2026-01-25
- 0.15.2 — 2026-01-25
- 0.15.1 — 2024-03-03
- 0.15.0 — 2023-10-27
- 0.14.1 — 2023-10-26
- 0.14.0 — 2023-10-22
- 0.13.2 — 2023-01-24
- 0.13.1 — 2022-06-30
- 0.13.0 — 2022-01-16
- 0.12.2 — 2021-07-01
- 0.12.1 — 2021-01-31
- 0.12.0 — 2020-12-12
- 0.11.1 — 2020-12-07
- 0.11.0 — 2020-12-07
- 0.10.0 — 2020-09-26
- … 17 more at https://npm.io/package/mini-css-class-name/versions

## README

# mini-css-class-name

[![CI](https://github.com/shoonia/mini-css-class-name/actions/workflows/ci.yml/badge.svg)](https://github.com/shoonia/mini-css-class-name/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/mini-css-class-name.svg)](https://www.npmjs.com/package/mini-css-class-name)

Minimum size unique CSS class names generator.
It can be used with [Webpack](#css-modules), [Vite](#vite), [Gatsby](https://github.com/shoonia/gatsby-plugin-mini-css-class-name#readme) and [PostCSS](#postcss-modules) ecosystems.

## Install

```bash
npm i mini-css-class-name --save-dev
# or
yarn add mini-css-class-name -D
```

## How to use

```js
const miniCssClassName = require('mini-css-class-name');

const generate = miniCssClassName({
  prefix: 'x__',
  suffix: '--y',
});

generate(); // x__a--y
generate(); // x__b--y
generate(); // x__c--y
```

## Reset method

```js
const miniCssClassName = require('mini-css-class-name');

const generate = miniCssClassName();

generate(); // a
generate(); // b
generate(); // c

generate.reset();

generate(); // a
```

## Exclude Pattern

You can use a regular expression to exclude any characters from the template string.

```js
// remove underscore and dash
const generate = miniCssClassName({ excludePattern: /[_-]/g });

// keep only alphabet characters
const generateABC = miniCssClassName({ excludePattern: /[^a-z]/gi });
```

Default template string

```js
'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_-0123456789';
```

## CSS Modules

### css-loader

Use with the Webpack [css-loader](https://github.com/webpack/css-loader#css-loader) resolver

```js
const createLocalIdent = require('mini-css-class-name/css-loader');
```

There are two ways to plugin it's depending on `css-loader` version.

#### css-loader <= 1.x || ~2.x

```js
const createLocalIdent = require('mini-css-class-name/css-loader');

const localIndent = createLocalIdent(/* options */);

module.exports = {

  // webpack config ...

  module: {
    rules: [
      {
        test: /\.css$/,
        loader: 'css-loader',
        options: {
          modules: true,
          getLocalIdent: localIndent,
        },
      },
    ],
  },
};
```

#### css-loader >= 3.0.0

```js
const createLocalIdent = require('mini-css-class-name/css-loader');

const localIndent = createLocalIdent(/* options */);

module.exports = {

  // webpack config ...

  module: {
    rules: [
      {
        test: /\.css$/,
        loader: 'css-loader',
        options: {
          modules: {
            getLocalIdent: localIndent,
          },
        },
      },
    ],
  },
};
```

#### Development and Production Environments

Setup of minimizing the class names only in the `production` build. In the `development` environment, you may use a human-readable class name template. It will be more easy to debug your projects.

```js
const createLocalIdent = require('mini-css-class-name/css-loader');

const localIndent = createLocalIdent(/* options */);

module.exports = {

  // webpack config ...

  module: {
    rules: [
      {
        test: /\.css$/,
        loader: 'css-loader',
        options: {
          modules: process.env.NODE_ENV === 'production'
            ? { getLocalIdent: localIndent }
            : { localIdentName: '[path][name]__[local]--[hash:base64:5]' },
        },
      },
    ],
  },
};
```

### postcss-modules

Use mini-css-class-name with the PostCSS [postcss-modules](https://github.com/madyankin/postcss-modules#postcss-modules) plugin

```js
const generateScopedName = require('mini-css-class-name/postcss-modules');
```

**Example**

```js
const { readFile } = require('node:fs/promises');
const postcss = require('postcss');
const postcssModules = require('postcss-modules');
const generateScopedName = require('mini-css-class-name/postcss-modules');

const getStyles = async () => {
  const path = './styles.css';
  const source = await readFile(path, 'utf8');

  let json;

  const { css } = await postcss([
    postcssModules({
      getJSON(_, jsonData) {
        json = jsonData;
      },
      generateScopedName: generateScopedName(/* options */),
    }),
  ]).process(source, { from: path });

  return { json, css };
};
```

### Vite

Use mini-css-class-name with [Vite's](https://vite.dev/) CSS Modules. The example shows how to generate minified class names in production and readable names in development.

```ts
import { defineConfig } from 'vite';
import generateScopedName from 'mini-css-class-name/postcss-modules';

export default defineConfig(({ mode }) => {
  const isProd = mode === 'production';

  return {

    // Vite config ...

    css: {
      modules: {
        generateScopedName: isProd
          ? generateScopedName(/* options */)
          : '[name]__[local]___[hash:base64:5]',
      },
    },
  };
});
```

**Development vs Production:**
- **Production**: Uses `generateScopedName()` to generate minimum size class names (e.g., `a`, `b`, `c`)
- **Development**: Uses readable template `[name]__[local]___[hash:base64:5]` for easier debugging

## Gatsby

You can also use it with [Gatsby](https://www.gatsbyjs.org/docs/add-custom-webpack-config/) v2, v3, v4 or v5

> [gatsby-plugin-mini-css-class-name](https://github.com/shoonia/gatsby-plugin-mini-css-class-name#readme)

## Options

|    Name          |   Type     | Default | Description |
|:----------------:|:----------:|:-------:|:-----------:|
| **prefix**       | `{String}` |  `''`   | A custom prefix will be added to each class name
| **suffix**       | `{String}` |  `''`   | A custom suffix will be added to each class name
|**excludePattern**| `{RegExp}` | `null`  | A regular expression for removing characters

## License

[MIT](./LICENSE)

---
_Source: https://npm.io/package/mini-css-class-name · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._