vite-plugin-css-module-types 1.0.0

package/src/plugin.ts

@@ -0,0 +1,287 @@
+import type { Plugin } from "vite";
+import { mkdir, readFile, writeFile, readdir, stat } from "node:fs/promises";
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+
+import {
+  normalizeFolderList,
+  shouldProcessFile,
+  patchViteModuleCode,
+  evaluateModuleExports,
+  buildClassNameIndex,
+  buildOriginalClassLineMap,
+  extractCssRuleBodies,
+  resolveClassEntries,
+  extractCssComments,
+  generateDtsContent,
+  generateDeclarationMap,
+  getInlineLineMappings,
+} from "./lib/index.ts";
+import { toCamelCase } from "./lib/camel-case.ts";
+import type { VitePluginCssModuleTypesOptions, DtsGenerationOptions } from "./lib/index.ts";
+
+async function findFiles(dir: string, suffix: string): Promise<string[]> {
+  const results: string[] = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...(await findFiles(full, suffix)));
+    } else if (entry.name.endsWith(suffix)) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Builds a class mapping from raw CSS source, simulating Vite's
+ * `localsConvention: 'camelCase'` behavior.
+ */
+function buildClassMappingFromSource(cssSource: string): Record<string, string> {
+  const mapping: Record<string, string> = {};
+  const classRegex = /\.([a-zA-Z_][\w-]*)/g;
+
+  for (const match of cssSource.matchAll(classRegex)) {
+    const name = match[1];
+    if (!name || name in mapping) continue;
+    mapping[name] = name;
+    const camel = toCamelCase(name);
+    if (camel !== name && !(camel in mapping)) {
+      mapping[camel] = name;
+    }
+  }
+  return mapping;
+}
+
+/** Creates a Vite dev-server plugin that generates `.d.ts` files for CSS Modules. */
+const DEFAULT_EXCLUDE_FOLDERS = ["node_modules", ".git", "dist", "build"];
+function viteCssModuleTypesPlugin(
+  options: VitePluginCssModuleTypesOptions = {
+    dtsOutputDir: ".css-module-types",
+  },
+): Plugin {
+  let rootDir = "";
+  let cssSourceMapEnabled = false;
+  const includeFolders = normalizeFolderList(options.include);
+  const excludeFolders = normalizeFolderList(
+    options.exclude ?? DEFAULT_EXCLUDE_FOLDERS,
+  );
+
+  let dtsGenOptions: DtsGenerationOptions;
+
+  const createdDirs = new Set<string>();
+  const contentCache = new Map<string, string>();
+
+  async function ensureDir(dirPath: string): Promise<void> {
+    if (createdDirs.has(dirPath)) return;
+    await mkdir(dirPath, { recursive: true });
+    createdDirs.add(dirPath);
+  }
+
+  /**
+   * Generates a `.d.ts` from raw CSS source (no Vite transform pipeline).
+   * Used by initial scan. Does not produce declaration maps.
+   */
+  async function generateDtsFromSource(absolutePath: string, force = false): Promise<void> {
+    const relativePath = path.relative(rootDir, absolutePath);
+
+    const dtsFileName = options.allowArbitraryExtensions
+      ? relativePath.replace(/\.css$/, ".d.css.ts")
+      : `${relativePath}.d.ts`;
+    const dtsFilePath = path.join(rootDir, options.dtsOutputDir, dtsFileName);
+
+    if (!force) {
+      try {
+        await stat(dtsFilePath);
+        return; // Already exists
+      } catch {
+        // Proceed
+      }
+    }
+
+    const source = await readFile(absolutePath, "utf-8");
+    const classMapping = buildClassMappingFromSource(source);
+    const comments = extractCssComments(source);
+    const originalClassLines = buildOriginalClassLineMap(source);
+    const cssRuleBodies = extractCssRuleBodies(source);
+
+    const entries = resolveClassEntries(classMapping, null, comments, originalClassLines, cssRuleBodies);
+    const fileName = path.basename(absolutePath);
+    const { content: dtsBody } = generateDtsContent(entries, fileName, absolutePath, dtsGenOptions);
+
+    const outputDir = path.join(rootDir, options.dtsOutputDir, path.dirname(relativePath));
+    await ensureDir(outputDir);
+    await writeFile(dtsFilePath, dtsBody);
+  }
+
+  /** Scans all `.module.css` files and generates initial `.d.ts` stubs. */
+  async function scanAllCssModules(): Promise<void> {
+    const scanRoots = includeFolders.length > 0
+      ? includeFolders.map((f) => path.join(rootDir, f))
+      : [rootDir];
+
+    const allFiles = (await Promise.all(
+      scanRoots.map((dir) => findFiles(dir, ".module.css")),
+    )).flat();
+
+    const eligible = allFiles.filter((f) => {
+      const rel = path.relative(rootDir, f);
+      return shouldProcessFile(rel, includeFolders, excludeFolders);
+    });
+
+    const results = await Promise.allSettled(
+      eligible.map((f) => generateDtsFromSource(f)),
+    );
+
+    let generated = 0;
+    for (const r of results) {
+      if (r.status === "fulfilled") generated++;
+    }
+
+    if (generated > 0) {
+      console.log(`[css-module-dts] Generated ${generated} declaration files on startup.`);
+    }
+  }
+
+  /**
+   * Core `.d.ts` generation from Vite's transformed CSS module code.
+   * Called from both `transform` and `handleHotUpdate`.
+   */
+  async function generateDtsFromTransform(code: string, id: string): Promise<void> {
+    const relativePath = path.relative(rootDir, id);
+
+    const patchedCode = patchViteModuleCode(code);
+    const { classMapping, cssText } = await evaluateModuleExports(patchedCode);
+
+    const lineMappings = cssSourceMapEnabled ? await getInlineLineMappings(cssText) : null;
+    const classIndex = lineMappings ? buildClassNameIndex(lineMappings) : null;
+
+    const source = await readFile(id, "utf-8");
+    const comments = extractCssComments(source);
+    const originalClassLines = buildOriginalClassLineMap(source);
+    const cssRuleBodies = extractCssRuleBodies(source);
+
+    const entries = resolveClassEntries(classMapping, classIndex, comments, originalClassLines, cssRuleBodies);
+
+    const fileName = path.basename(id);
+    const { content: dtsBody, lineMappings: dtsLineMappings } = generateDtsContent(
+      entries, fileName, id, dtsGenOptions,
+    );
+    const outputDir = path.join(rootDir, options.dtsOutputDir, path.dirname(relativePath));
+    await ensureDir(outputDir);
+
+    const dtsFileName = options.allowArbitraryExtensions
+      ? relativePath.replace(/\.css$/, ".d.css.ts")
+      : `${relativePath}.d.ts`;
+    const dtsFilePath = path.join(rootDir, options.dtsOutputDir, dtsFileName);
+
+    const useDeclarationMap =
+      (options.declarationMap ?? true) && cssSourceMapEnabled && dtsLineMappings.length > 0;
+
+    const dtsBaseName = path.basename(dtsFileName);
+    const mapFileName = `${dtsBaseName}.map`;
+
+    const dtsContent = useDeclarationMap
+      ? `${dtsBody}//# sourceMappingURL=${mapFileName}\n`
+      : dtsBody;
+
+    let mapContent: string | undefined;
+    if (useDeclarationMap) {
+      const cssRelativePath = path.relative(outputDir, id);
+      const totalDtsLines = dtsContent.split("\n").length;
+      mapContent = generateDeclarationMap(dtsBaseName, cssRelativePath, dtsLineMappings, totalDtsLines);
+    }
+
+    const mapFilePath = useDeclarationMap ? path.join(outputDir, mapFileName) : undefined;
+
+    // Dirty-check: skip write when both .d.ts and .d.ts.map are identical.
+    try {
+      const existingDts = await readFile(dtsFilePath, "utf-8");
+      if (existingDts === dtsContent) {
+        if (!mapFilePath || !mapContent) return;
+        try {
+          const existingMap = await readFile(mapFilePath, "utf-8");
+          if (existingMap === mapContent) return;
+        } catch {
+          // Map file doesn't exist yet
+        }
+      }
+    } catch {
+      // .d.ts doesn't exist yet
+    }
+
+    await writeFile(dtsFilePath, dtsContent);
+
+    if (mapFilePath && mapContent) {
+      await writeFile(mapFilePath, mapContent);
+    }
+  }
+
+  return {
+    name: "vite-plugin-css-module-types",
+    apply: "serve",
+    enforce: "post",
+
+    configResolved(config) {
+      rootDir = config.root;
+      cssSourceMapEnabled = config.css.devSourcemap;
+      mkdirSync(path.join(rootDir, options.dtsOutputDir), { recursive: true });
+      dtsGenOptions = { namedExports: options.namedExports };
+    },
+
+    configureServer() {
+      scanAllCssModules().catch((err) => {
+        console.warn("[css-module-dts] Initial scan failed:", err);
+      });
+    },
+
+    async transform(code, id) {
+      if (!id.endsWith(".module.css")) return null;
+
+      const relativePath = path.relative(rootDir, id);
+      if (!shouldProcessFile(relativePath, includeFolders, excludeFolders)) return null;
+
+      if (contentCache.get(id) === code) return null;
+      contentCache.set(id, code);
+
+      try {
+        await generateDtsFromTransform(code, id);
+      } catch (error) {
+        console.warn(
+          `[css-module-dts] Failed to generate types for ${relativePath}:`,
+          error instanceof Error ? error.message : error,
+        );
+      }
+
+      return null;
+    },
+
+    handleHotUpdate({ file }) {
+      if (!file.endsWith(".module.css")) return;
+
+      const relativePath = path.relative(rootDir, file);
+      if (!shouldProcessFile(relativePath, includeFolders, excludeFolders)) return;
+
+      // Clear content cache so the next transform processes the file.
+      contentCache.delete(file);
+
+      // Re-generate .d.ts from raw source immediately (without waiting for
+      // Vite's transform pipeline). This ensures types are up-to-date even
+      // if the module isn't re-requested by the browser right away.
+      generateDtsFromSource(file, true).catch((err) => {
+        console.warn(`[css-module-dts] HMR re-generation failed for ${relativePath}:`, err);
+      });
+
+      // Return undefined to let Vite handle HMR normally.
+      return;
+    },
+  };
+}
+
+export default viteCssModuleTypesPlugin;

package/src/tests/camel-case.spec.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from "vitest";
+import { toCamelCase } from "../lib/camel-case.ts";
+
+describe("toCamelCase", () => {
+  it("converts kebab-case to camelCase", () => {
+    expect(toCamelCase("my-class")).toBe("myClass");
+  });
+
+  it("converts multiple dashes", () => {
+    expect(toCamelCase("my-cool-long-class")).toBe("myCoolLongClass");
+  });
+
+  it("returns the same string when no dashes are present", () => {
+    expect(toCamelCase("button")).toBe("button");
+  });
+
+  it("handles leading single character segments", () => {
+    expect(toCamelCase("a-b-c")).toBe("aBC");
+  });
+
+  it("preserves underscores", () => {
+    expect(toCamelCase("my_class")).toBe("my_class");
+  });
+
+  it("handles mixed dashes and underscores", () => {
+    expect(toCamelCase("my_class-name")).toBe("my_className");
+  });
+
+  it("handles digits after dash", () => {
+    expect(toCamelCase("section-2")).toBe("section2");
+  });
+
+  it("returns empty string for empty input", () => {
+    expect(toCamelCase("")).toBe("");
+  });
+});