{"id":23772150,"url":"https://github.com/connorjs/css-typed","last_synced_at":"2025-09-05T17:31:17.533Z","repository":{"id":146586138,"uuid":"618215666","full_name":"connorjs/css-typed","owner":"connorjs","description":"TypeScript declaration generator for CSS files","archived":false,"fork":false,"pushed_at":"2024-08-06T12:52:32.000Z","size":351,"stargazers_count":4,"open_issues_count":6,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-31T03:46:38.602Z","etag":null,"topics":["css","modules","types","typescript"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/css-typed","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/connorjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2023-03-24T01:43:28.000Z","updated_at":"2024-08-06T12:52:35.000Z","dependencies_parsed_at":"2023-12-25T16:51:33.642Z","dependency_job_id":"4bbeca0d-4604-42bd-ae23-0b25c5ffa4ce","html_url":"https://github.com/connorjs/css-typed","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/connorjs/css-typed","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connorjs%2Fcss-typed","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connorjs%2Fcss-typed/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connorjs%2Fcss-typed/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connorjs%2Fcss-typed/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/connorjs","download_url":"https://codeload.github.com/connorjs/css-typed/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connorjs%2Fcss-typed/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273790554,"owners_count":25168674,"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","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["css","modules","types","typescript"],"created_at":"2025-01-01T04:53:02.447Z","updated_at":"2025-09-05T17:31:17.156Z","avatar_url":"https://github.com/connorjs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# css-typed\n\nTypeScript declaration generator for CSS files.\n\n\u003cimg alt=\"css-typed logo\" src=\"images/css-typed.svg\" width=\"400\"\u003e\n\n\u003c/div\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTable of Contents\u003c/strong\u003e\u003c/summary\u003e\n\n- [Usage](#usage)\n- [Options](#options)\n- [Recipes](#recipes)\n- [Motivation](#motivation)\n- [Contributing](#contributing)\n- [Implementation details](#implementation-details)\n\n\u003c/details\u003e\n\n## Usage\n\n### Install\n\nInstall the CLI tool as a dev dependency.\n\n```shell\nnpm install --save-dev css-typed\n```\n\n### Run\n\nRun `css-typed` and pass it a glob targeting your CSS files.\n\n```shell\nnpx css-typed \"src/**/*.css\"\n```\n\nThis will generate `.d.css.ts` files next to the original source files.\n\nSee the [run script recipe](#run-script) for adding to your `package.json`.\n\n\u003e [!NOTE]\n\u003e\n\u003e A CSS module file with the name `foo.module.css` will emit `foo.module.d.css.ts`.\n\n### Configure\n\nConfigure TypeScript to allow arbitrary extensions (TS 5+).\n\n```json\n{\n\t\"compilerOptions\": {\n\t\t\"allowArbitraryExtensions\": true\n\t}\n}\n```\n\nAdd `*.d.css.ts` to your `.gitignore` if appropriate.\n(See [#4] for more information about alternative output directory.)\n\n```shell\necho '*.d.css.ts' \u003e\u003e .gitignore\n```\n\n[#4]: https://github.com/connorjs/css-typed/issues/4\n\n## Options\n\nThe following table lists the options `css-typed` supports.\nAlso run `css-typed -h` on the command line.\n\n|      CLI option      |   Default    | Description                            |\n| :------------------: | :----------: | :------------------------------------- |\n|  `-c` or `--config`  |  Heuristics  | Custom path to the configuration file. |\n| `--localsConvention` | `dashesOnly` | Style of exported class names.         |\n\n### config\n\n`css-typed` supports loading options from a configuration file instead of using command line arguments.\nTo load from a custom path, use the `-c` or `--config` option.\nBy default, `css-typed` looks in the following locations.\nExtensionless \"rc\" files can have JSON or YAML format.\n\n- Package file: `css-typed` property in `package.json` or `package.yaml`\n- Root rc files: `.csstypedrc` with no extension or one of `json`, `yaml`, `yml`, `js`, `cjs`, or `mjs`\n- Config folder rc files: `.config/csstypedrc` with no extension or one of `json`, `yaml`, `yml`, `js`, `cjs`, or `mjs`\n- Root config files: `css-typed.config` with an extension of `js`, `cjs`, or `mjs`\n\n\u003cdetails\u003e\n\u003csummary\u003eLook under the hood\u003c/summary\u003e\n\nUnder the hood, `css-typed` uses [lilconfig] to load configuration files.\nIt supports YAML files via [js-yaml].\n\nSee [config.ts](src/cli/config.ts) for the implementation.\n\n\u003c/details\u003e\n\n[lilconfig]: https://www.npmjs.com/package/lilconfig\n[js-yaml]: https://www.npmjs.com/package/js-yaml\n\n### localsConvention\n\nInspired by [postcss localsConvention](https://github.com/madyankin/postcss-modules#localsconvention).\nAdds `none` option value to use the class name as-is.\n\nThe `--localsConvention` option changes the style of exported class names, the exports in your TS (i.e., the JS names).\n\n`css-typed` will only camelize dashes in class names by default (the `dashesOnly` option value).\nIt will not preserve the original class name.\nFor example, `my-class` becomes `myClass` and you cannot use `my-class` in JS/TS code.\n\nModern bundlers or build system such as Vite and Gatsby support this transformation.\nThe default matches CSS naming practices (`kebab-case`).\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e Note that `camelCase` and `dashes` MAY have TypeScript bugs.\n\u003e TypeScript 5.6 may help with the named exports for these.\n\u003e\n\u003e If you encounter a bug, please file an issue.\n\u003e In the mean-time, consider using `camelCaseOnly` instead.\n\u003e (Or `dashesOnly` which is the default.)\n\n## Recipes\n\n### Run script\n\nTo run it as part of your build, you will likely include it as a run script, maybe as `codegen`, `css-typed`, or `pretsc`.\n\n```json\n{\n\t\"scripts\": {\n\t\t\"codegen\": \"css-typed \\\"src/**/*.css\\\"\",\n\t\t\"css-typed\": \"css-typed \\\"src/**/*.css\\\"\",\n\t\t\"pretsc\": \"css-typed \\\"src/**/*.css\\\"\",\n\t\t\"tsc\": \"tsc\"\n\t}\n}\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e Use `\\\"` in your run scripts for Windows OS compatibility.\n\n### Watch\n\nThe CLI does not have built-in watch support.\nFeel free to [nodemon] or similar.\n\n```json\n{\n\t\"scripts\": {\n\t\t\"codegen\": \"css-typed \\\"src/**/*.css\\\"\",\n\t\t\"codegen:watch\": \"nodemon -x \\\"npm run codegen\\\" -w src -e css\"\n\t}\n}\n```\n\n[nodemon]: https://www.npmjs.com/package/nodemon\n\n## Motivation\n\n[typescript-plugin-css-modules] provides a great IDE experience, but cannot perform build-failing type-checking.\nFurthermore, the traditional TypeScript ambient module definition fails the `noUncheckedIndexedAccess` strict check and causes issues with typed ESLint rules.\n\n```ts\n// This does not provide strict typing\ndeclare module \"*.module.css\" {\n\tconst classes: { [key: string]: string };\n\texport default classes; // It also uses default export 😿\n}\n```\n\n[typed-css-modules] and [typed-scss-modules] exist, but the former does not have recent activity and the latter focuses on SCSS.\n(My current (2023/2024) interests involve modern CSS only.)\nBoth depend on [css-modules-loader-core], which appears [abandoned][174].\n\nTherefore, I wrote my own (very basic) implementation.\nSee [§Implementation details](#implementation-details) for more information.\n\n[typescript-plugin-css-modules]: https://www.npmjs.com/package/typescript-plugin-css-modules\n[typed-css-modules]: https://www.npmjs.com/package/typed-css-modules\n[typed-scss-modules]: https://www.npmjs.com/package/typed-scss-modules\n[css-modules-loader-core]: https://www.npmjs.com/package/css-modules-loader-core\n[174]: https://github.com/css-modules/css-modules-loader-core/issues/174\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## Implementation details\n\nThis (very basic) implementation uses [glob] for file matching and [css-tree] for CSS parsing.\nIt extracts CSS classes (`ClassSelector` in CSS Tree’s AST) and exports them as `string` constants (named exports).\n\nThe CSS-file class name is modified for JS export according to the [localsConvention](#localsconvention) option.\nThe implementation matches PostCSS.\n\nI chose CSS Tree after a brief search because it had a nice API, good documentation, and supported CSS nesting (a requirement for my original use case).\n\n`css-typed` uses [Commander.js][commander] for command line parsing and [lilconfig] for configuration file loading.\n\nThe “brand” image/logo combines the public CSS 3 and TypeScript logos with a basic plus icon in between.\nSee [css-typed.svg](images/css-typed.svg).\n\n[glob]: https://www.npmjs.com/package/glob\n[css-tree]: https://www.npmjs.com/package/css-tree\n[commander]: https://www.npmjs.com/package/commander\n[lilconfig]: https://www.npmjs.com/package/lilconfig\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconnorjs%2Fcss-typed","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconnorjs%2Fcss-typed","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconnorjs%2Fcss-typed/lists"}