`xxx` is not allowed because it is not a valid JavaScript identifier.

[iwashi1t]

Dear mizdra,

Thank you for your great work on happy-css-modules — I really appreciate the excellent library.

I’m currently trying to migrate to css-modules-kit, but I encountered the error mentioned in the title when running cmk.

In my environment, I use Vite with CSS Modules and follow a kebab-case naming convention for class names (hoge-fuga) for personal reasons. I configure localsConvention: 'camelCaseOnly' in Vite so that class names can be used in camelCase on the JS/TS side.

happy-css-modules works fine with this setup, but I'm wondering: does css-modules-kit require class names to be camelCase in the CSS as well?

Thank you for your time, and I’d appreciate it if you could take a look when convenient.

---

みずどらさん

happy-css-modules から大変お世話になっております。素晴らしいライブラリをありがとうございます。
こちらのライブラリに移行させていただこうと使用を試してみたのですが、 cmk 実行時にタイトルのエラーが表示されます。

こちらの環境としてはVite + CSS Moduleを使用しており、CSSクラス名の命名には宗教上の理由からケバブケース( hoge-fuga 形式)を採用しています。Vite configの localsConvention を camelCaseOnly に設定して、JS(TS)側ではキャメルケースを使用できるようにしています。

happy-css-modules では hcm コマンドの localsConvention オプションが利用可能ですが、 cmk の場合はCSSクラス名にキャメルケースしか使用できないような制限があったりしますでしょうか？

お忙しいところ恐れ入りますが、ご確認のほどよろしくお願いいたします。

[mizdra]

Thank you for opening this issue!

css-modules-kit intentionally disallows non-JavaScript identifiers in class names. There are two reasons for this.

Reason 1: Renaming becomes complicated

The first reason is that depending on the value of the localsConvention option, it may not be possible to accurately rename classes.

For example, consider a project that uses localsConvention: 'camelCaseOnly', and the following code:

/* Foo.module.css */
  .foo {
/* ^^^ (1) */
    color: red;
  }

// Foo.tsx
import styles from './Foo.module.css';
styles['foo'];
//      ^^^ ... (2)

If (1) is renamed to hoge-fuga, what should (2) be renamed to—hoge-fuga or hogeFuga? Both are valid ways to reference the class name. Ideally, if the user prefers the xxx-yyy format, it should rename to that; if they prefer xxxYyy, it should rename accordingly. However, changing the renaming behavior based on user preference would make the design of css-modules-kit unnecessarily complex. To be honest, I don't want to implement that.

Reason 2: Volar.js limitations

The second reason is technical—non-JavaScript identifiers cannot be supported due to limitations. Internally, css-modules-kit uses Volar.js to convert .module.css files into TypeScript declaration files. Then, it feeds those declaration files into the TypeScript Language Server, enabling cross-language features between TypeScript and CSS code.

/* Foo.module.css */
@value local1: string;
.local2 { color: red }

// Foo.module.css.d.ts
// @ts-nocheck
const styles = {
  local1: '' as readonly string,
  local2: '' as readonly string,
};
export default styles;

ref:

css-modules-kit/packages/core/src/dts-creator.ts

Lines 32 to 124 in 16e5703

	/**
	* Create a d.ts file from a CSS module file.
	* @example
	* If the CSS module file is:
	* ```css
	* @import './a.module.css';
	* @value local1: string;
	* @value imported1, imported2 as aliasedImported2 from './b.module.css';
	* .local2 { color: red }
	* ```
	* The d.ts file would be:
	* ```ts
	* // @ts-nocheck
	* const styles = {
	* local1: '' as readonly string,
	* local2: '' as readonly string,
	* ...(await import('./a.module.css')).default,
	* imported1: (await import('./b.module.css')).default.imported1,
	* aliasedImported2: (await import('./b.module.css')).default.imported2,
	* };
	* export default styles;
	* ```
	*/
	export function createDts(
	{ fileName, localTokens, tokenImporters: _tokenImporters }: CSSModule,
	options: CreateDtsOptions,
	): { text: string; mapping: CodeMapping; linkedCodeMapping: LinkedCodeMapping } {
	const mapping: CodeMapping = { sourceOffsets: [], lengths: [], generatedOffsets: [] };
	const linkedCodeMapping: LinkedCodeMapping = {
	sourceOffsets: [],
	lengths: [],
	generatedOffsets: [],
	generatedLengths: [],
	};
	// Filter external files
	const tokenImporters = _tokenImporters.filter((tokenImporter) => {
	const resolved = options.resolver(tokenImporter.from, { request: fileName });
	return resolved !== undefined && options.matchesPattern(resolved);
	});
	// MEMO: Depending on the TypeScript compilation options, the generated type definition file contains compile errors.
	// For example, it contains `Top-level 'await' expressions are only allowed when the 'module' option is set to ...` error.
	//
	// If `--skipLibCheck` is false, those errors will be reported by `tsc`. However, these are negligible errors.
	// Therefore, `@ts-nocheck` is added to the generated type definition file.
	let text = `// @ts-nocheck\ndeclare const ${STYLES_EXPORT_NAME} = {\n`;
	for (const token of localTokens) {
	text += ` `;
	mapping.sourceOffsets.push(token.loc.start.offset);
	mapping.generatedOffsets.push(text.length);
	mapping.lengths.push(token.name.length);
	text += `${token.name}: '' as readonly string,\n`;
	}
	for (const tokenImporter of tokenImporters) {
	if (tokenImporter.type === 'import') {
	text += ` ...(await import(`;
	mapping.sourceOffsets.push(tokenImporter.fromLoc.start.offset - 1);
	mapping.lengths.push(tokenImporter.from.length + 2);
	mapping.generatedOffsets.push(text.length);
	text += `'${tokenImporter.from}')).default,\n`;
	} else {
	// eslint-disable-next-line no-loop-func
	tokenImporter.values.forEach((value, i) => {
	const localName = value.localName ?? value.name;
	const localLoc = value.localLoc ?? value.loc;
	text += ` `;
	mapping.sourceOffsets.push(localLoc.start.offset);
	mapping.lengths.push(localName.length);
	mapping.generatedOffsets.push(text.length);
	linkedCodeMapping.sourceOffsets.push(text.length);
	linkedCodeMapping.lengths.push(localName.length);
	text += `${localName}: (await import(`;
	if (i === 0) {
	mapping.sourceOffsets.push(tokenImporter.fromLoc.start.offset - 1);
	mapping.lengths.push(tokenImporter.from.length + 2);
	mapping.generatedOffsets.push(text.length);
	}
	text += `'${tokenImporter.from}')).default.`;
	mapping.sourceOffsets.push(value.loc.start.offset);
	mapping.lengths.push(value.name.length);
	mapping.generatedOffsets.push(text.length);
	linkedCodeMapping.generatedOffsets.push(text.length);
	linkedCodeMapping.generatedLengths.push(value.name.length);
	text += `${value.name},\n`;
	});
	}
	}
	text += `};\nexport default ${STYLES_EXPORT_NAME};\n`;
	return { text, mapping, linkedCodeMapping };
	}

Furthermore, css-modules-kit uses a code mapping feature of Volar.js to associate local2 in Foo.module.css with local2 in Foo.module.css.d.ts. This enables class renaming and code navigation across TypeScript and CSS code.

ref: https://github.com/mizdra/honey-css-modules/blob/73c18500c260381a1155306b3b2974d37c5b1f31/packages/ts-plugin/src/language-plugin.ts#L64-L67

If we were to allow non-JavaScript identifiers like hoge-fuga, the properties in styles would need to be quoted:

// Foo.module.css.d.ts
// @ts-nocheck
const styles = {
  'hoge-fuga': '' as readonly string,
  'local2': '' as readonly string,
};
export default styles;

However, doing so appears to break Volar.js’s code mapping functionality. As a result, class renaming and code navigation no longer work properly.

• PoC: Support class names in any format #177

This is probably due to a bug or technical limitation in Volar.js. It may eventually be resolved on Volar.js’s side, but for now, it is a blocker that prevents css-modules-kit from supporting non-JavaScript identifiers in class names.

---

issue を立てていただきありがとうございます！

css-modules-kit がクラス名に 非 JavaScript identifier を許可しないのは意図的です。それには2つの理由があります。

理由1: rename の方法が複雑になる

1つ目の理由は localsConvention のオプション値次第では、正確なクラスの rename が行えないためです。

例えば localsConvention: 'camelCaseOnly' を利用するプロジェクトで、以下のようなコードがあるとします。

/* Foo.module.css */
  .foo {
/* ^^^ (1) */
    color: red;
  }

// Foo.tsx
import styles from './Foo.module.css';
styles['foo'];
//      ^^^ ... (2)

このとき、(1) で hoge-fuga に rename をした場合、(2) は hoge-fuga と hogeFuga のどちらに rename されるべきでしょうか? どちらもクラス名を参照する方法として正しいです。理想的にはユーザが xxx-yyy 形式を好むならそれを、xxxYyy 形式を好むならそれに rename するのが良いでしょう。しかし、ユーザの好みに応じて rename の方法を変更するのは、css-modules-kit の設計を複雑にしてしまいます。正直なところ、私はそれを実装したくありません。

理由2: Volar.js の技術的な制限

2つ目の理由は、技術的な理由で非 JavaScript identifier のクラス名を許可できないからです。css-modules-kit は内部では Volar.js を用いて .module.css を TypeScript の型定義ファイルに変換しています。そしてその変換した型定義ファイルを TypeScript の Language Server に読み込ませることで、TypeScript コードと CSS コードを横断する言語機能を実現しています。

/* Foo.module.css */
@value local1: string;
.local2 { color: red }

// Foo.module.css.d.ts
// @ts-nocheck
const styles = {
  local1: '' as readonly string,
  local2: '' as readonly string,
};
export default styles;

ref:

css-modules-kit/packages/core/src/dts-creator.ts

Lines 32 to 124 in 16e5703

	/**
	* Create a d.ts file from a CSS module file.
	* @example
	* If the CSS module file is:
	* ```css
	* @import './a.module.css';
	* @value local1: string;
	* @value imported1, imported2 as aliasedImported2 from './b.module.css';
	* .local2 { color: red }
	* ```
	* The d.ts file would be:
	* ```ts
	* // @ts-nocheck
	* const styles = {
	* local1: '' as readonly string,
	* local2: '' as readonly string,
	* ...(await import('./a.module.css')).default,
	* imported1: (await import('./b.module.css')).default.imported1,
	* aliasedImported2: (await import('./b.module.css')).default.imported2,
	* };
	* export default styles;
	* ```
	*/
	export function createDts(
	{ fileName, localTokens, tokenImporters: _tokenImporters }: CSSModule,
	options: CreateDtsOptions,
	): { text: string; mapping: CodeMapping; linkedCodeMapping: LinkedCodeMapping } {
	const mapping: CodeMapping = { sourceOffsets: [], lengths: [], generatedOffsets: [] };
	const linkedCodeMapping: LinkedCodeMapping = {
	sourceOffsets: [],
	lengths: [],
	generatedOffsets: [],
	generatedLengths: [],
	};
	// Filter external files
	const tokenImporters = _tokenImporters.filter((tokenImporter) => {
	const resolved = options.resolver(tokenImporter.from, { request: fileName });
	return resolved !== undefined && options.matchesPattern(resolved);
	});
	// MEMO: Depending on the TypeScript compilation options, the generated type definition file contains compile errors.
	// For example, it contains `Top-level 'await' expressions are only allowed when the 'module' option is set to ...` error.
	//
	// If `--skipLibCheck` is false, those errors will be reported by `tsc`. However, these are negligible errors.
	// Therefore, `@ts-nocheck` is added to the generated type definition file.
	let text = `// @ts-nocheck\ndeclare const ${STYLES_EXPORT_NAME} = {\n`;
	for (const token of localTokens) {
	text += ` `;
	mapping.sourceOffsets.push(token.loc.start.offset);
	mapping.generatedOffsets.push(text.length);
	mapping.lengths.push(token.name.length);
	text += `${token.name}: '' as readonly string,\n`;
	}
	for (const tokenImporter of tokenImporters) {
	if (tokenImporter.type === 'import') {
	text += ` ...(await import(`;
	mapping.sourceOffsets.push(tokenImporter.fromLoc.start.offset - 1);
	mapping.lengths.push(tokenImporter.from.length + 2);
	mapping.generatedOffsets.push(text.length);
	text += `'${tokenImporter.from}')).default,\n`;
	} else {
	// eslint-disable-next-line no-loop-func
	tokenImporter.values.forEach((value, i) => {
	const localName = value.localName ?? value.name;
	const localLoc = value.localLoc ?? value.loc;
	text += ` `;
	mapping.sourceOffsets.push(localLoc.start.offset);
	mapping.lengths.push(localName.length);
	mapping.generatedOffsets.push(text.length);
	linkedCodeMapping.sourceOffsets.push(text.length);
	linkedCodeMapping.lengths.push(localName.length);
	text += `${localName}: (await import(`;
	if (i === 0) {
	mapping.sourceOffsets.push(tokenImporter.fromLoc.start.offset - 1);
	mapping.lengths.push(tokenImporter.from.length + 2);
	mapping.generatedOffsets.push(text.length);
	}
	text += `'${tokenImporter.from}')).default.`;
	mapping.sourceOffsets.push(value.loc.start.offset);
	mapping.lengths.push(value.name.length);
	mapping.generatedOffsets.push(text.length);
	linkedCodeMapping.generatedOffsets.push(text.length);
	linkedCodeMapping.generatedLengths.push(value.name.length);
	text += `${value.name},\n`;
	});
	}
	}
	text += `};\nexport default ${STYLES_EXPORT_NAME};\n`;
	return { text, mapping, linkedCodeMapping };
	}

更に、Volar.js の code mapping 機能を用いて、Foo.module.css の local2 と、Foo.module.css.d.ts の local2 を関連付けています。これにより、TypeScript コードと CSS コードを横断したクラスの rename や、コードジャンプが可能になります。

ref: https://github.com/mizdra/honey-css-modules/blob/73c18500c260381a1155306b3b2974d37c5b1f31/packages/ts-plugin/src/language-plugin.ts#L64-L67

もし hoge-fuga のような非 JavaScript identifier を許可するなら、styles のプロパティをクオートで囲む必要があるでしょう。

// Foo.module.css.d.ts
// @ts-nocheck
const styles = {
  'hoge-fuga': '' as readonly string,
  'local2': '' as readonly string,
};
export default styles;

しかしこれを行うと、Volar.js の code mapping 機能が正しく動作しなくなるようです。その結果クラスの rename やコードジャンプが壊れます。

• PoC: Support class names in any format #177

この問題はおそらく Volar.js のバグか、技術的な制約によるものです。いずれ Volar.js 側でそれが解決されるかもしれませんが、現時点では css-modules-kit がクラス名に 非 JavaScript identifier を許可するためのブロッカーになってます。

[iwashi1t]

Thank you very much for your detailed explanation, including the technical background.

I now have a clear understanding of why css-modules-kit intentionally does not support non-JavaScript identifiers—especially the complexity it would introduce in the rename process and the limitations of Volar.js's code mapping.

I'll consider adapting to camelCase. I'm looking forward to seeing how css-modules-kit continues to evolve!

---

ご丁寧かつ技術的背景まで詳細にご説明いただき、ありがとうございます。

css-modules-kit が非 JavaScript identifier を意図的にサポート対象外としている理由、特に rename 処理の複雑化や Volar.js の code mapping の制約について、大変よく理解できました。

camelCase を受け入れる方向で検討します。引き続き css-modules-kit の進化を楽しみにしております！