Support namedExports option (#182)

mizdra · web-flow · commit 9b40191c209b · 2025-06-08T01:04:53.000+09:00
* update example

* update README

* add E2E test for named exports

* support `namedExports` options

* add changelog
diff --git a/.changeset/true-kiwis-kneel.md b/.changeset/true-kiwis-kneel.md
@@ -0,0 +1,7 @@
+---
+'@css-modules-kit/ts-plugin': minor
+'@css-modules-kit/codegen': minor
+'@css-modules-kit/core': minor
+---
+
+feat: support `namedExports` option
diff --git a/README.md b/README.md
@@ -116,7 +116,9 @@ In TypeScript, the `include`/`exclude` properties specify which `*.ts` files to
 
 ### `cmkOptions.dtsOutDir`
 
-Specifies the directory where `*.d.ts` files are output. The default is `"generated"`.
+Type: `string`, Default: `"generated"`
+
+Specifies the directory where `*.d.ts` files are output.
 
 ```jsonc
 {
@@ -131,7 +133,9 @@ Specifies the directory where `*.d.ts` files are output. The default is `"genera
 
 ### `cmkOptions.arbitraryExtensions`
 
-Determines whether to generate `*.module.d.css.ts` instead of `*.module.css.d.ts`. The default is `false`.
+Type: `boolean`, Default: `false`
+
+Determines whether to generate `*.module.d.css.ts` instead of `*.module.css.d.ts`.
 
 ```jsonc
 {
@@ -144,6 +148,23 @@ Determines whether to generate `*.module.d.css.ts` instead of `*.module.css.d.ts
 }
 ```
 
+### `cmkOptions.namedExports`
+
+Type: `boolean`, Default: `false`
+
+Determines whether to generate named exports in the d.ts file instead of a default export.
+
+```jsonc
+{
+  "compilerOptions": {
+    // ...
+  },
+  "cmkOptions": {
+    "namedExports": true,
+  },
+}
+```
+
 ## Limitations
 
 - Sass/Less are not supported to simplify the implementation
diff --git a/example/generated/src/a.module.css.d.ts b/example/generated/src/a.module.css.d.ts
@@ -1,11 +1,10 @@
 // @ts-nocheck
-declare const styles = {
-  a_1: '' as readonly string,
-  a_2: '' as readonly string,
-  a_2: '' as readonly string,
-  a_3: '' as readonly string,
-  ...(await import('./b.module.css')).default,
-  c_1: (await import('./c.module.css')).default.c_1,
-  c_alias: (await import('./c.module.css')).default.c_2,
-};
-export default styles;
+export var a_1: string;
+export var a_2: string;
+export var a_2: string;
+export var a_3: string;
+export * from './b.module.css';
+export {
+  c_1,
+  c_2 as c_alias,
+} from './c.module.css';
diff --git a/example/generated/src/b.module.css.d.ts b/example/generated/src/b.module.css.d.ts
@@ -1,6 +1,3 @@
 // @ts-nocheck
-declare const styles = {
-  b_1: '' as readonly string,
-  b_2: '' as readonly string,
-};
-export default styles;
+export var b_1: string;
+export var b_2: string;
diff --git a/example/generated/src/c.module.css.d.ts b/example/generated/src/c.module.css.d.ts
@@ -1,6 +1,3 @@
 // @ts-nocheck
-declare const styles = {
-  c_1: '' as readonly string,
-  c_2: '' as readonly string,
-};
-export default styles;
+export var c_1: string;
+export var c_2: string;
diff --git a/example/generated/src/d.module.css.d.ts b/example/generated/src/d.module.css.d.ts
diff --git a/example/src/index.tsx b/example/src/index.tsx
@@ -1,9 +1,3 @@
-import styles from './a.module.css';
+import * as styles from "./a.module.css";
 
 styles.a_1;
-styles.a_2;
-styles.a_3;
-styles.b_1;
-styles.b_2;
-styles.c_1;
-styles.c_alias;
diff --git a/example/tsconfig.json b/example/tsconfig.json
@@ -12,5 +12,8 @@
     "paths": { "@/*": ["./*"] },
     "rootDirs": [".", "generated"],
     "types": [] // Simplify tsserver.log
+  },
+  "cmkOptions": {
+    "namedExports": true
   }
 }
diff --git a/packages/codegen/src/runner.ts b/packages/codegen/src/runner.ts
@@ -41,11 +41,11 @@ async function parseCSSModuleByFileName(fileName: string): Promise<ParseCSSModul
  */
 async function writeDtsByCSSModule(
   cssModule: CSSModule,
-  { dtsOutDir, basePath, arbitraryExtensions }: CMKConfig,
+  { dtsOutDir, basePath, arbitraryExtensions, namedExports }: CMKConfig,
   resolver: Resolver,
   matchesPattern: MatchesPattern,
 ): Promise<void> {
-  const dts = createDts(cssModule, { resolver, matchesPattern });
+  const dts = createDts(cssModule, { resolver, matchesPattern, namedExports });
   await writeDtsFile(dts.text, cssModule.fileName, {
     outDir: dtsOutDir,
     basePath,
diff --git a/packages/core/src/config.test.ts b/packages/core/src/config.test.ts
@@ -27,7 +27,9 @@ describe('readTsConfigFile', () => {
             "module": "esnext"
           },
           "cmkOptions": {
-            "dtsOutDir": "generated/cmk"
+            "dtsOutDir": "generated/cmk",
+            "arbitraryExtensions": false,
+            "namedExports": true
           }
         }
       `,
@@ -38,6 +40,8 @@ describe('readTsConfigFile', () => {
         includes: ['src'],
         excludes: ['src/test'],
         dtsOutDir: 'generated/cmk',
+        arbitraryExtensions: false,
+        namedExports: true,
       },
       compilerOptions: expect.objectContaining({
         module: ts.ModuleKind.ESNext,
diff --git a/packages/core/src/config.ts b/packages/core/src/config.ts
@@ -15,6 +15,8 @@ export interface CMKConfig {
   excludes: string[];
   dtsOutDir: string;
   arbitraryExtensions: boolean;
+  /** Whether to generate named exports in the d.ts file instead of a default export. */
+  namedExports: boolean;
   /**
    * A root directory to resolve relative path entries in the config file to.
    * This is an absolute path.
@@ -68,6 +70,7 @@ interface UnnormalizedRawConfig {
   excludes?: string[];
   dtsOutDir?: string;
   arbitraryExtensions?: boolean;
+  namedExports?: boolean;
 }
 
 /**
@@ -134,6 +137,17 @@ function parseRawData(raw: unknown, tsConfigSourceFile: ts.TsConfigSourceFile):
         });
       }
     }
+    if ('namedExports' in raw.cmkOptions) {
+      if (typeof raw.cmkOptions.namedExports === 'boolean') {
+        result.config.namedExports = raw.cmkOptions.namedExports;
+      } else {
+        result.diagnostics.push({
+          category: 'error',
+          text: `\`namedExports\` in ${tsConfigSourceFile.fileName} must be a boolean.`,
+          // MEMO: Location information can be obtained from `tsConfigSourceFile.statements`, but this is complicated and will be omitted.
+        });
+      }
+    }
   }
   return result;
 }
@@ -146,6 +160,7 @@ function mergeParsedRawData(base: ParsedRawData, overrides: ParsedRawData): Pars
   if (overrides.config.dtsOutDir !== undefined) result.config.dtsOutDir = overrides.config.dtsOutDir;
   if (overrides.config.arbitraryExtensions !== undefined)
     result.config.arbitraryExtensions = overrides.config.arbitraryExtensions;
+  if (overrides.config.namedExports !== undefined) result.config.namedExports = overrides.config.namedExports;
   result.diagnostics.push(...overrides.diagnostics);
   return result;
 }
@@ -226,6 +241,7 @@ export function readConfigFile(project: string): CMKConfig {
     excludes: (config.excludes ?? []).map((e) => join(basePath, e)),
     dtsOutDir: join(basePath, config.dtsOutDir ?? 'generated'),
     arbitraryExtensions: config.arbitraryExtensions ?? false,
+    namedExports: config.namedExports ?? false,
     basePath,
     configFileName,
     compilerOptions,
diff --git a/packages/core/src/dts-creator.test.ts b/packages/core/src/dts-creator.test.ts
@@ -6,6 +6,7 @@ import { fakeCSSModule } from './test/css-module.js';
 const options: CreateDtsOptions = {
   resolver: (specifier, { request }) => join(dirname(request), specifier),
   matchesPattern: () => true,
+  namedExports: false,
 };
 
 function fakeLoc(offset: number) {
@@ -377,4 +378,84 @@ describe('createDts', () => {
       }
     `);
   });
+  test('creates d.ts file with named exports', () => {
+    expect(
+      createDts(
+        fakeCSSModule({
+          localTokens: [
+            { name: 'local1', loc: fakeLoc(0) },
+            { name: 'local2', loc: fakeLoc(1) },
+          ],
+          tokenImporters: [
+            { type: 'import', from: './a.module.css', fromLoc: fakeLoc(2) },
+            {
+              type: 'value',
+              values: [
+                { name: 'imported1', loc: fakeLoc(3) },
+                { name: 'imported2', loc: fakeLoc(4), localName: 'aliasedImported2', localLoc: fakeLoc(5) },
+              ],
+              from: './b.module.css',
+              fromLoc: fakeLoc(6),
+            },
+          ],
+        }),
+        { ...options, namedExports: true },
+      ),
+    ).toMatchInlineSnapshot(`
+      {
+        "linkedCodeMapping": {
+          "generatedLengths": [
+            9,
+          ],
+          "generatedOffsets": [
+            125,
+          ],
+          "lengths": [
+            16,
+          ],
+          "sourceOffsets": [
+            138,
+          ],
+        },
+        "mapping": {
+          "generatedOffsets": [
+            26,
+            53,
+            83,
+            112,
+            125,
+            138,
+            163,
+          ],
+          "lengths": [
+            6,
+            6,
+            16,
+            9,
+            9,
+            16,
+            16,
+          ],
+          "sourceOffsets": [
+            0,
+            1,
+            1,
+            3,
+            4,
+            5,
+            5,
+          ],
+        },
+        "text": "// @ts-nocheck
+      export var local1: string;
+      export var local2: string;
+      export * from './a.module.css';
+      export {
+        imported1,
+        imported2 as aliasedImported2,
+      } from './b.module.css';
+      ",
+      }
+    `);
+  });
 });
diff --git a/packages/core/src/dts-creator.ts b/packages/core/src/dts-creator.ts
diff --git a/packages/ts-plugin/e2e/named-exports.test.ts b/packages/ts-plugin/e2e/named-exports.test.ts
diff --git a/packages/ts-plugin/src/index.ts b/packages/ts-plugin/src/index.ts
diff --git a/packages/ts-plugin/src/language-plugin.ts b/packages/ts-plugin/src/language-plugin.ts

Original file line number	Diff line number	Diff line change
`@@ -12,5 +12,8 @@`
`12`	`12`	`"paths": { "@/": ["./"] },`
`13`	`13`	`"rootDirs": [".", "generated"],`
`14`	`14`	`"types": [] // Simplify tsserver.log`
	`15`	`+ },`
	`16`	`+ "cmkOptions": {`
	`17`	`+ "namedExports": true`
`15`	`18`	`}`
`16`	`19`	`}`