vite-plugin-css-module-types 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# vite-plugin-css-module-types
+
+Vite **dev-server** plugin that generates `.d.ts` declarations for CSS Modules. With `css.devSourcemap` enabled, includes JSDoc links to original CSS source lines and declaration maps for "Go to Definition".
+
+Inspired by [vite-plugin-css-module-dts](https://github.com/lovetingyuan/vite-plugin-css-module-dts) and [typed-css-modules](https://github.com/Quramy/typed-css-modules).
+
+## Quick start
+
+```ts
+// vite.config.ts
+import viteCssModuleTypesPlugin from 'vite-plugin-css-module-types';
+
+export default defineConfig({
+  css: { devSourcemap: true },
+  plugins: [
+    viteCssModuleTypesPlugin({
+      dtsOutputDir: 'tmp/vite-plugin-css-module-types', // add to .gitignore
+      include: ['apps/web/src'],
+      exclude: ['apps/web/src/legacy'],
+    }),
+  ],
+});
+```
+
+Add to your `.gitignore`:
+
+```# vite-plugin-css-module-types
+tmp/vite-plugin-css-module-types/
+```
+
+Add to your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "rootDirs": [
+      "./src",
+      "./tmp/vite-plugin-css-module-types/src"
+    ]
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+    "tmp/vite-plugin-css-module-types/src"
+  ]
+}
+```
+If you use `/src` in your `rootDirs` (as in the example above), it's best to also add the corresponding path from the output directory (e.g., `./tmp/vite-plugin-css-module-types/src`) to avoid issues with path mapping.
+
+
+
+> Runs only in `serve` mode. Processes `*.module.css` files.
+
+## Options
+
+| Option                     | Type                 | Default     | Description                                                          |
+| -------------------------- | -------------------- | ----------- | -------------------------------------------------------------------- |
+| `dtsOutputDir`             | `string`             | —           | **Required.** Output directory for `.d.ts` files, relative to root.  |
+| `include`                  | `string \| string[]` | `undefined` | Folder(s) to include (prefix-matched).                               |
+| `exclude`                  | `string \| string[]` | `undefined` | Folder(s) to exclude. **Wins** when both match.                      |
+| `namedExports`             | `boolean`            | `false`     | Emit `export declare const` per class.                               |
+| `allowArbitraryExtensions` | `boolean`            | `false`     | Use TS 5.0+ `.d.module.css.ts` naming instead of `.module.css.d.ts`. |
+| `declarationMap`           | `boolean`            | `true`      | Generate `.d.ts.map` for "Go to Definition". Needs `devSourcemap`.   |
+
+Path matching is **prefix-based** (not glob). Separators are normalized, `./` and trailing `/` are stripped.
+
+## Output examples
+
+### Default mode
+
+```ts
+declare const styles: {
+  /** [↗ button.module.css:3](file:///abs/path/button.module.css#L3) */
+  readonly 'btn-primary': '_btn-primary_x1y2z';
+};
+export default styles;
+```
+
+### With `namedExports: true`
+
+```ts
+/** [↗ button.module.css:3](file:///abs/path/button.module.css#L3) */
+export declare const btnPrimary: string;
+
+declare const styles: {
+  readonly 'btn-primary': '_btn-primary_x1y2z';
+  readonly btnPrimary: '_btn-primary_x1y2z';
+};
+export default styles;
+```
+
+### With CSS docblock comments
+
+```css
+/** Main call-to-action button. */
+.btn-primary { color: blue; }
+```
+
+````ts
+declare const styles: {
+  /**
+   * ```txt
+   * Main call-to-action button.
+   * ```
+   * ---
+   * ```css
+   * .btn-primary { color: blue; }
+   * ```
+   * ---
+   * [↗ button.module.css:2](file:///abs/path/button.module.css#L2)
+   */
+  readonly 'btn-primary': '_btn-primary_x1y2z';
+};
+export default styles;
+````
+
+### Empty module
+
+```ts
+export {};
+```
+
+## Dependencies
+
+- [source-map](https://www.npmjs.com/package/source-map) — inline CSS sourcemap parsing
+- [@jridgewell/sourcemap-codec](https://www.npmjs.com/package/@jridgewell/sourcemap-codec) — VLQ encoding for declaration maps
+- Vite ^8 (peer), TypeScript ^5 (peer)