{"id":15046867,"url":"https://github.com/unknown4unnamed/pcssmdts","last_synced_at":"2025-05-12T15:27:26.279Z","repository":{"id":37962991,"uuid":"501708148","full_name":"unknown4unnamed/pcssmdts","owner":"unknown4unnamed","description":"Generates type definitions for your CSS Modules","archived":false,"fork":false,"pushed_at":"2025-05-06T11:10:48.000Z","size":350,"stargazers_count":4,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-06T11:56:27.319Z","etag":null,"topics":["cli","postcss","typed-css-modules","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unknown4unnamed.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-06-09T15:24:50.000Z","updated_at":"2025-02-02T19:17:21.000Z","dependencies_parsed_at":"2024-11-14T16:27:24.332Z","dependency_job_id":"bbebc166-5d8b-4e8a-8917-092de27e4deb","html_url":"https://github.com/unknown4unnamed/pcssmdts","commit_stats":{"total_commits":15,"total_committers":1,"mean_commits":15.0,"dds":0.0,"last_synced_commit":"cd2b8e405088be4800d6a1acb4023f8708a98ed5"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown4unnamed%2Fpcssmdts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown4unnamed%2Fpcssmdts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown4unnamed%2Fpcssmdts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown4unnamed%2Fpcssmdts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unknown4unnamed","download_url":"https://codeload.github.com/unknown4unnamed/pcssmdts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253765050,"owners_count":21960667,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","postcss","typed-css-modules","typescript"],"created_at":"2024-09-24T20:53:40.722Z","updated_at":"2025-05-12T15:27:26.226Z","avatar_url":"https://github.com/unknown4unnamed.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Test](https://github.com/unknown4unnamed/pcssmdts/actions/workflows/test.yml/badge.svg)](https://github.com/unknown4unnamed/pcssmdts/actions/workflows/test.yml)\n![Coverage](https://img.shields.io/badge/coverage-95.03%25-brightgreen)\n[![npm](https://img.shields.io/badge/npm-v0.2.0-blue)](https://www.npmjs.com/package/pcssmdts)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node Version](https://img.shields.io/badge/node-%3E%3D16.19.1%20%3C21-brightgreen)](https://nodejs.org)\n[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)\n\n# pcssmdts\n\nA powerful TypeScript definition generator for PostCSS-powered CSS Modules, ensuring type safety and providing IDE intellisense for your CSS class names.\n\n## Why pcssmdts?\n\n### The Problem\n\nWhen working with CSS Modules in TypeScript projects, especially in large design systems or component libraries, you often face these challenges:\n\n1. **Type Safety Gaps**: CSS class names are essentially strings, making them prone to typos and runtime errors\n2. **Poor IDE Support**: No autocomplete for CSS class names means developers need to constantly reference CSS files\n3. **Refactoring Difficulties**: Renaming CSS classes becomes risky without TypeScript's refactoring support\n4. **Design System Maintenance**: Ensuring consistent class usage across a large codebase is challenging\n\n### The Solution\n\npcssmdts bridges these gaps by:\n\n1. **Type Safety**: Automatically generates TypeScript definitions for your CSS Modules\n2. **IDE Integration**: Provides full IntelliSense support for class names\n3. **Refactoring Support**: Makes class names refactorable through TypeScript's tooling\n4. **PostCSS Integration**: Works seamlessly with your existing PostCSS setup\n\n### Comparison with IDE Solutions\n\nWhile IDE plugins like `typescript-plugin-css-modules` can provide type support during development, pcssmdts offers several advantages:\n\n1. **CI/CD Integration**:\n\n   - Generate type definitions as part of your build process\n   - Catch type errors in CI before they reach production\n   - No reliance on developer IDE configuration\n\n2. **Team Consistency**:\n\n   - Ensures all team members have the same type definitions\n   - Works regardless of IDE or editor preferences\n   - No need to maintain plugin configurations across the team\n\n3. **Build-time Validation**:\n\n   - Validates CSS Modules during build time\n   - Integrates with your existing TypeScript compilation\n   - Prevents deployment of mismatched class names\n\n4. **Source Control**:\n   - Generated types can be committed (optional)\n   - Enables type checking in environments without PostCSS setup\n   - Perfect for consuming libraries in other projects\n\n```typescript\n// With IDE plugin only:\n// - Types only available during development\n// - Requires IDE configuration\n// - May vary between team members\n\n// With pcssmdts:\n// - Types available everywhere\n// - Part of your build process\n// - Consistent across team and CI\nimport styles from './Button.module.css';\n// TypeScript knows exactly what's available\nconst className = styles.button; // ✅ Type-safe\n```\n\n### PostCSS Configuration Flexibility\n\nOne of the key advantages of pcssmdts is its seamless integration with PostCSS, allowing you to:\n\n1. **Use Your Existing Setup**:\n\n   ```js\n   // postcss.config.js\n   module.exports = {\n     plugins: [\n       require('postcss-nested'),\n       require('tailwindcss'),\n       require('autoprefixer'),\n       require('postcss-modules')({\n         // your custom options\n         generateScopedName: '[name]__[local]___[hash:base64:5]',\n       }),\n     ],\n   };\n   ```\n\n2. **Support Modern CSS Features**:\n\n   ```css\n   /* Your CSS Module with modern syntax */\n   .button {\n     /* Nesting (via postcss-nested) */\n     \u0026:hover {\n       background: theme('colors.blue.600');\n     }\n\n     /* Custom Media Queries */\n     @media (--dark-mode) {\n       background: theme('colors.gray.800');\n     }\n\n     /* CSS Custom Properties */\n     --button-padding: 1rem;\n     padding: var(--button-padding);\n   }\n   ```\n\n3. **Framework Integration**:\n\n   - Works with Tailwind CSS for utility-first styling\n   - Compatible with CSS preprocessors (SASS/LESS) through PostCSS plugins\n   - Integrates with popular frameworks:\n\n     ```tsx\n     // Next.js\n     import styles from './Button.module.css';\n\n     // React\n     import styles from './Button.module.scss'; // With SASS\n\n     // Vue with TypeScript\n     import styles from './Button.module.css';\n     ```\n\n\u003e **Note**: CSS Modules are different from CSS-in-JS solutions. While CSS-in-JS libraries like styled-components or emotion write styles in JavaScript, CSS Modules let you write traditional CSS files with local scope and static analysis. pcssmdts is specifically designed for CSS Modules, providing type safety without runtime overhead.\n\n4. **Custom Naming Conventions**:\n   ```js\n   // postcss.config.js with custom class naming\n   module.exports = {\n     plugins: [\n       require('postcss-modules')({\n         generateScopedName: (name, filename, css) =\u003e {\n           // Your custom naming logic\n           return `myApp_${name}_${hashString(css)}`;\n         },\n       }),\n     ],\n   };\n   ```\n\nThis flexibility means you can:\n\n- Use modern CSS features while maintaining type safety\n- Integrate with your existing build pipeline\n- Customize class name generation to match your needs\n- Support complex CSS transformations while keeping type definitions accurate\n\n### Real-World Use Cases\n\n#### 1. Design System Development\n\n```tsx\n// Before: No type safety or autocomplete\nconst Button = ({ variant }) =\u003e (\n  \u003cbutton className={`btn btn--${variant}`}\u003eClick me\u003c/button\u003e\n);\n\n// After: Full type safety and autocomplete\nimport styles from './Button.module.css';\n\ntype ButtonVariant = 'primary' | 'secondary';\n\nconst Button = ({ variant }: { variant: ButtonVariant }) =\u003e (\n  \u003cbutton\n    className={`${styles.btn} ${\n      variant === 'primary' ? styles.btnPrimary : styles.btnSecondary\n    }`}\n  \u003e\n    Click me\n  \u003c/button\u003e\n);\n```\n\n#### 2. Large-Scale Application Migration\n\nWhen migrating a large application to use CSS Modules:\n\n```tsx\n// Before: Global CSS with potential naming conflicts\nconst Header = () =\u003e (\n  \u003cheader className=\"app-header\"\u003e\n    \u003cnav className=\"navigation\"\u003e\n      \u003ca className=\"nav-link active\"\u003eHome\u003c/a\u003e\n    \u003c/nav\u003e\n  \u003c/header\u003e\n);\n\n// After: Scoped CSS Modules with type safety\nimport styles from './Header.module.css';\n\nconst Header = () =\u003e (\n  \u003cheader className={styles.header}\u003e\n    \u003cnav className={styles.navigation}\u003e\n      \u003ca className={`${styles.link} ${styles.linkActive}`}\u003eHome\u003c/a\u003e\n    \u003c/nav\u003e\n  \u003c/header\u003e\n);\n```\n\n#### 3. Component Library Development\n\nWhen building a shared component library:\n\n```tsx\n// components/Card/Card.module.css\n.card {\n  /* styles */\n}\n.cardHeader {\n  /* styles */\n}\n.cardContent {\n  /* styles */\n}\n.cardFooter {\n  /* styles */\n}\n\n// components/Card/Card.tsx\nimport styles from './Card.module.css';\n\nexport const Card = ({\n  header,\n  children,\n  footer\n}: CardProps) =\u003e (\n  \u003cdiv className={styles.card}\u003e\n    {header \u0026\u0026 \u003cdiv className={styles.cardHeader}\u003e{header}\u003c/div\u003e}\n    \u003cdiv className={styles.cardContent}\u003e{children}\u003c/div\u003e\n    {footer \u0026\u0026 \u003cdiv className={styles.cardFooter}\u003e{footer}\u003c/div\u003e}\n  \u003c/div\u003e\n);\n```\n\n### Benefits in Practice\n\n1. **Development Speed**:\n\n   - Immediate feedback on invalid class names\n   - Autocomplete reduces need to reference CSS files\n   - Faster onboarding for new team members\n\n2. **Code Quality**:\n\n   - Catch CSS class typos at compile time\n   - Ensure consistent class usage across components\n   - Make refactoring CSS class names safe and easy\n\n3. **Maintenance**:\n   - Track CSS class usage across the codebase\n   - Safely remove unused classes\n   - Easier code reviews with type checking\n\n## Features\n\n- 🚀 Fast and efficient d.ts generation\n- 🔍 Full PostCSS support with custom plugins and configurations\n- 🎯 Automatic camelCase class name conversion\n- 💡 IDE intellisense support\n- ✅ TypeScript compilation-time type checking\n- 🛠 Configurable output formats\n- 📦 Zero runtime overhead\n\n## Requirements\n\n- Node.js: `\u003e=16.19.1 \u003c21`\n- PostCSS configuration file (optional, will use defaults if not provided)\n\n## Installation\n\n### Quick Start with npx (Recommended)\n\nThe fastest way to use this utility is through `npx` without installation:\n\n```sh\nnpx pcssmdts \"src/**/*.module.css\"\n```\n\n### Local Installation\n\nAdd it as a development dependency to your project:\n\n```sh\n# npm\nnpm install pcssmdts --save-dev\n\n# yarn\nyarn add pcssmdts -D\n\n# pnpm\npnpm add -D pcssmdts\n```\n\nAdd to your package.json scripts:\n\n```json\n{\n  \"scripts\": {\n    \"generate:style-defs\": \"pcssmdts \\\"src/**/*.module.css\\\"\",\n    \"generate:style-defs:watch\": \"pcssmdts \\\"src/**/*.module.css\\\" --watch\"\n  }\n}\n```\n\n## How It Works\n\npcssmdts operates in three main steps:\n\n1. **CSS Module Detection**: Scans your project for CSS module files based on the provided glob pattern\n2. **PostCSS Processing**: Processes your CSS files using your PostCSS configuration\n3. **TypeScript Definition Generation**: Creates corresponding .d.ts files with type definitions\n\n### Example Project Structure\n\n```\nsrc/\n├── components/\n│   └── Button/\n│       ├── styles.module.css\n│       ├── styles.module.css.d.ts  (generated)\n│       └── Button.tsx\n```\n\n### CSS Module Example\n\n```css\n/* styles.module.css */\n.button {\n  display: flex;\n\n  \u0026--primary {\n    background: blue;\n  }\n\n  \u0026--secondary {\n    background: gray;\n  }\n}\n\n.icon-wrapper {\n  margin-right: 8px;\n}\n```\n\n### Generated TypeScript Definition\n\n```typescript\n// styles.module.css.d.ts\ndeclare const styles: {\n  readonly button: string;\n  readonly buttonPrimary: string;\n  readonly buttonSecondary: string;\n  readonly iconWrapper: string;\n};\nexport = styles;\n```\n\n### React Component Usage\n\n```tsx\nimport styles from './styles.module.css';\n\nexport const Button: React.FC\u003c{\n  variant?: 'primary' | 'secondary';\n}\u003e = ({ variant = 'primary' }) =\u003e {\n  return (\n    \u003cbutton\n      className={`${styles.button} ${\n        variant === 'primary' ? styles.buttonPrimary : styles.buttonSecondary\n      }`}\n    \u003e\n      \u003cspan className={styles.iconWrapper}\u003e{/* Your icon here */}\u003c/span\u003e\n      Click me\n    \u003c/button\u003e\n  );\n};\n```\n\n## CLI Options\n\nThe CLI is powered by [typed-css-modules](https://github.com/Quramy/typed-css-modules) under the hood, providing robust TypeScript definition generation.\n\n```\npcssmdts \u003csource\u003e [options]\n\nArguments:\n  source                    Source pattern for CSS module files (e.g., \"src/**/*.module.css\")\n\nBasic options:\n  -v, --verbose            Enable verbose logging                      [boolean]\n  -c, --config            Custom PostCSS config path                   [string]\n  -k, --keep              Keep compiled CSS files                      [boolean]\n  -w, --watch             Watch mode for file changes                  [boolean]\n\ntyped-css-modules options:\n  -n, --namedExports      Use named exports in .d.ts files    [boolean] [default: false]\n  --camelCase             Convert CSS class names to camelCase [choices: \"true\", \"false\", \"dashes\"]\n  --outDir               Output directory for generated d.ts files. When specified, all generated .d.ts files will be placed in this directory, regardless of their original location. [string]\n  --eol                  End of line character                   [string]\n\nGeneral:\n  --help                  Show help information                        [boolean]\n  --version              Show version number                          [boolean]\n```\n\n### Common Use Cases\n\n1. **Basic Usage**\n   By default, .d.ts files are generated next to their corresponding CSS modules:\n\n   ```sh\n   pcssmdts \"src/**/*.module.css\"\n   ```\n\n   Result:\n\n   ```\n   src/\n   ├── components/\n   │   └── Button/\n   │       ├── styles.module.css\n   │       └── styles.module.css.d.ts  (generated here)\n   ```\n\n2. **Using outDir**\n   Place all generated .d.ts files in a specific directory:\n\n   ```sh\n   pcssmdts \"src/**/*.module.css\" --outDir types\n   ```\n\n   Result:\n\n   ```\n   src/\n   ├── components/\n   │   └── Button/\n   │       └── styles.module.css\n   └── types/\n       └── styles.module.css.d.ts  (generated here)\n   ```\n\n   Note: When using `outDir`, all generated .d.ts files will be placed flat in the specified directory, regardless of their original location in the source tree.\n\n3. **Keep Compiled Files for Debugging**\n   Preserve PostCSS-processed files for debugging or inspection:\n\n   ```sh\n   pcssmdts \"src/**/*.module.css\" -k\n   ```\n\n   Result:\n\n   ```\n   src/\n   ├── components/\n   │   └── Button/\n   │       ├── styles.module.css              (original)\n   │       ├── _compiled.styles.module.css    (processed CSS)\n   │       └── styles.module.css.d.ts         (generated types)\n   ```\n\n   The `_compiled.*.css` files contain the processed CSS after all PostCSS transformations. This is useful for:\n\n   - Debugging CSS transformations\n   - Verifying PostCSS plugin output\n   - Inspecting final class names after scoping\n\n4. **Watch Mode**\n\n   ```sh\n   pcssmdts \"src/**/*.module.css\" -w\n   ```\n\n5. **Custom PostCSS Config**\n\n   ```sh\n   pcssmdts \"src/**/*.module.css\" -c ./config/postcss.config.js\n   ```\n\n6. **Named Exports with Custom Output Directory**\n\n   ```sh\n   pcssmdts \"src/**/*.module.css\" -n --outDir types\n   ```\n\n7. **CamelCase with Dashes**\n\n   ```sh\n   pcssmdts \"src/**/*.module.css\" --camelCase dashes\n   ```\n\n8. **Keep Compiled Files with Custom EOL**\n\n   ```sh\n   pcssmdts \"src/**/*.module.css\" -k --eol \"\\n\"\n   ```\n\n### Watch Mode\n\nWatch mode (`-w` or `--watch`) automatically regenerates TypeScript definitions when your CSS modules change. Here's how to verify it's working:\n\n1. **Start Watch Mode**\n\n   ```sh\n   pcssmdts \"src/**/*.module.css\" -w\n   ```\n\n2. **Verify Initial Generation**\n\n   - Check that `.d.ts` files are generated for all your CSS modules\n   - You should see console output indicating the initial generation\n\n3. **Test File Changes**\n\n   ```sh\n   # 1. Open your CSS module in an editor\n   # 2. Add a new class\n   .new-class {\n     color: red;\n   }\n   # 3. Save the file\n   ```\n\n   The watcher should automatically:\n\n   - Detect the file change\n   - Regenerate the `.d.ts` file\n   - Show console output about the regeneration\n\n4. **Verify Type Updates**\n\n   ```tsx\n   // Your component file\n   import styles from './styles.module.css';\n\n   // The new class should be available with TypeScript intellisense\n   \u003cdiv className={styles.newClass} /\u003e; // If using camelCase\n   ```\n\n5. **Common Watch Mode Issues**\n   - If changes aren't detected, ensure you're watching the correct directory\n   - Some IDEs may need to refresh the TypeScript server to pick up new definitions\n   - Use `-v` flag for verbose logging to debug watch mode issues:\n     ```sh\n     pcssmdts \"src/**/*.module.css\" -w -v\n     ```\n\n## PostCSS Configuration\n\npcssmdts uses [postcss-load-config](https://github.com/postcss/postcss-load-config) to load your PostCSS configuration. It supports all standard PostCSS config files:\n\n- `postcss.config.js`\n- `.postcssrc`\n- `package.json` with `postcss` field\n\nExample PostCSS config:\n\n```js\n// postcss.config.js\nmodule.exports = {\n  plugins: [\n    require('postcss-nested'),\n    require('postcss-modules')({\n      // your options here\n    }),\n    // other plugins...\n  ],\n};\n```\n\n## Best Practices\n\n1. **Git Ignore**\n   Add generated files to your .gitignore:\n\n   ```\n   **/*.module.css.d.ts\n   **/_compiled.*.css\n   ```\n\n2. **CI Integration**\n   Run type generation before TypeScript compilation:\n\n   ```json\n   {\n     \"scripts\": {\n       \"build\": \"pcssmdts \\\"src/**/*.module.css\\\" \u0026\u0026 tsc\"\n     }\n   }\n   ```\n\n3. **Development Workflow**\n   Use watch mode during development:\n   ```json\n   {\n     \"scripts\": {\n       \"dev\": \"concurrently \\\"pcssmdts 'src/**/*.module.css' -w\\\" \\\"your-dev-server\\\"\"\n     }\n   }\n   ```\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- 📝 [Documentation](https://github.com/unknown4unnamed/pcssmdts#readme)\n- 🐛 [Issue Tracker](https://github.com/unknown4unnamed/pcssmdts/issues)\n- 💬 [Discussions](https://github.com/unknown4unnamed/pcssmdts/discussions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funknown4unnamed%2Fpcssmdts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funknown4unnamed%2Fpcssmdts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funknown4unnamed%2Fpcssmdts/lists"}