generic-names

4.0.0 verified Sat Apr 25 auth: no javascript

Helper for building generic names with pattern interpolation, similar to webpack's css-loader. Stable v4.0.0 (latest) uses loader-utils and xxhash64 by default for hashing. Generates scoped class names for CSS Modules, commonly used with postcss-modules-scope. Designed to produce consistent, platform-independent names (fixed in v2.0.1). Breaking changes in v3 and v4 altered hash output — consumers must ensure matching versions with css-loader to avoid class name mismatches.

Common errors

error TypeError: generate is not a function ↓

cause Importing named export instead of default export.

fix

Use 'import generate from "generic-names"' or 'const generate = require("generic-names")'.

error Cannot find module 'loader-utils' ↓

cause loader-utils is a peer dependency not installed automatically.

fix

Run 'npm install loader-utils' (or add it to project dependencies).

error Class names differ between development and production builds ↓

cause Different versions of loader-utils or generic-names used in different environments.

fix

Ensure exact version locking for generic-names and loader-utils across environments.

Warnings

breaking v4.0.0 updated loader-utils; xxhash64 is now the default for [hash] and [contenthash]. Existing names using these patterns will change. ↓

fix If you rely on stable hashes, pin to v3.x or explicitly configure hashFunction in loader-utils options.

breaking v3.0.0 replaced '+' with '\x00' in generated names, causing new class name output, especially for hashed patterns. ↓

fix Upgrade css-loader to >=4 to keep class names in sync.

breaking v2.0.0 changed default context from process.cwd() to postcss.cwd() when used with postcss-modules-scope. Also updated loader-utils from ^0.2.16 to ^1.1.0. ↓

fix If using without postcss, explicitly set context: process.cwd() to retain old behavior.

gotcha When using with css-loader, the version of generic-names must match the version used internally by css-loader to avoid class name mismatches. ↓

fix Use the same major version of generic-names as the one bundled with your css-loader, or pin both.

Install

npm install generic-names

yarn add generic-names

pnpm add generic-names

Imports

default
wrong
```
import { generate } from 'generic-names'
```
correct
```
import generate from 'generic-names'
```
The package exports a default function, not a named export. TypeScript types expect default import.

default (require)

wrong

const { generate } = require('generic-names')

correct

const generate = require('generic-names')

CommonJS require returns the default function directly.

type GenericNamesOptions

wrong

import { GenericNamesOptions } from 'generic-names'

correct

import type { GenericNamesOptions } from 'generic-names'

Options type is exported as a named type, not a value.

Quickstart

Shows how to import and use the default export to create a name generator, with pattern and options.

import generate from 'generic-names';

const generateName = generate('[name]__[local]___[hash:base64:5]', {
  context: process.cwd(),
  hashPrefix: 'custom',
});

const className = generateName('foo', '/case/source.css'); // 'source__foo___3mRq8'
console.log(className);