{"id":30067250,"url":"https://github.com/gracile-web/vite-plugin-standard-css-modules","last_synced_at":"2026-03-05T19:01:08.405Z","repository":{"id":220899820,"uuid":"752539006","full_name":"gracile-web/vite-plugin-standard-css-modules","owner":"gracile-web","description":"Provide a CSSStyleSheet or a CSSResult (Lit) for using with import attributes. Using the \"with\" keyword and \"type : css\".","archived":false,"fork":false,"pushed_at":"2024-08-03T20:56:44.000Z","size":154,"stargazers_count":16,"open_issues_count":4,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-02T13:39:29.597Z","etag":null,"topics":["bundler","constructable-stylesheets","css-modules","lit","polyfill","tc39","vite"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gracile-web.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2024-02-04T06:10:10.000Z","updated_at":"2026-02-26T19:40:46.000Z","dependencies_parsed_at":"2024-05-02T06:50:00.238Z","dependency_job_id":"a0124420-176e-4050-a56f-68c8f3cdad37","html_url":"https://github.com/gracile-web/vite-plugin-standard-css-modules","commit_stats":null,"previous_names":["juliancataldo/vite-plugin-standard-css-modules","gracile-web/vite-plugin-standard-css-modules"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gracile-web/vite-plugin-standard-css-modules","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gracile-web%2Fvite-plugin-standard-css-modules","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gracile-web%2Fvite-plugin-standard-css-modules/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gracile-web%2Fvite-plugin-standard-css-modules/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gracile-web%2Fvite-plugin-standard-css-modules/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gracile-web","download_url":"https://codeload.github.com/gracile-web/vite-plugin-standard-css-modules/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gracile-web%2Fvite-plugin-standard-css-modules/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30144700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T16:58:46.102Z","status":"ssl_error","status_checked_at":"2026-03-05T16:58:45.706Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["bundler","constructable-stylesheets","css-modules","lit","polyfill","tc39","vite"],"created_at":"2025-08-08T08:46:16.110Z","updated_at":"2026-03-05T19:01:08.393Z","avatar_url":"https://github.com/gracile-web.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vite-plugin-standard-css-modules\n\n[![NPM](https://img.shields.io/npm/v/vite-plugin-standard-css-modules)](https://www.npmjs.com/package/vite-plugin-standard-css-modules)\n![Downloads](https://img.shields.io/npm/dt/vite-plugin-standard-css-modules)\n[![ISC License](https://img.shields.io/npm/l/vite-plugin-standard-css-modules)](./LICENSE)\n[![GitHub](https://img.shields.io/badge/Repository-222222?logo=github)](https://github.com/JulianCataldo/vite-plugin-standard-css-modules)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://makeapullrequest.com)  \n[![TypeScript](https://img.shields.io/badge/TypeScript-333333?logo=typescript)](http://www.typescriptlang.org/)\n[![Prettier](https://img.shields.io/badge/Prettier-333333?logo=prettier)](https://prettier.io)\n[![EditorConfig](https://img.shields.io/badge/EditorConfig-333333?logo=editorconfig)](https://editorconfig.org)\n\nProvides a CSSStyleSheet or a CSSResult (Lit) for use with [import attributes](https://tc39.es/proposal-import-attributes/).  \nUsing the \"with\" keyword and \"type : css\".\n\n---\n\nAllows:\n\n```ts\nimport myStyles1 from './my-styles-1.css' with { type: 'css' };\nimport myStyles2 from './my-styles-2.css' assert { type: 'css' }; // ⚠️ Deprecated\nimport myStyles3 from './my-styles-3.css'; // ⚠️ Non-standard\n```\n\nTo be imported seamlessly, from your project or a dependency (mono-repo…).\n\n---\n\nThe API ensures strict defaults while allowing opt-in flexibility, especially for catering to Node usage.\n\n## Installation\n\n```\nnpm i vite-plugin-standard-css-modules\n```\n\nVite or compatible frameworks configuration:\n\n```ts\nimport { standardCssModules } from 'vite-plugin-standard-css-modules';\n\nconst myEnvironmentViteConfig = {\n\t// ...\n\n\tplugins: [\n\t\tstandardCssModules({\n\t\t\t/* transformationMode: \"CSSResult\", */\n\n\t\t\tfilter: (params) =\u003e {\n\t\t\t\t// console.log({ params });\n\n\t\t\t\t// if (filePath === \"foo\") return false;\n\t\t\t\t// if (params.ssr) return false;\n\n\t\t\t\treturn true;\n\t\t\t},\n\n\t\t\t/* log: false, */\n\n\t\t\tssrOnlyLit: true, // Removes the need for `?lit`, server-side.\n\t\t}),\n\t],\n};\n```\n\n## Configuration\n\n### `targetSsr`/`targetClient`\n\n`CSSStyleSheet` (**default** for `targetClient`) is agnostic, and platform-native.  \nMight not work with **SSR** until JS server runtimes support this API or a working minimal implementation.\n\n`CSSResult` (**default** for `targetSsr`) is Lit-specific. On the client, it can lazily provide a `CSSStyleSheet`.  \nWorks with **SSR**. Set as **default** if executed in an SSR environment. That might change in the future, when Node will support `CSSStyleSheet`.\n\n### `emptySsr`/`emptyClient` (`boolean`)\n\nUseful if, for example, you're using Lit hydration and don't want to load the style on client,\nsince they are already provided in the Declarative Shadow Dom as a `\u003cstyle\u003e` tag. In that case,\nyou'll set `emptyClient` to `true`, resulting in a dummy, empty stylesheet module.\n\n\u003c!-- ### `filter`\n\n`(params: { id: string; importer?: string; ssr?: boolean }): boolean =\u003e myMatcher(filePath, myPatterns)`\n\nProvides a callback for selective CSS file handling.\nFrom there, you can use your favorite glob paths matcher, like picomatch, minimatch…\n`ssr` is true when the import is from a server-side context.\n\nThis hook is useful if you have some non-standards CSS imports you want to preserve, by migrating to the standard syntax, gradually. --\u003e\n\n\u003c!-- ### `ssrOnlyLit`\n\n`boolean` (default: `false`)\n\nRemoves the need for the `?lit` query on the server to get a usable asset.\nBy opting in, you'll get a `CSSStyleSheet` client side and a `CSSResult` while on the server-side, automatically.\nAll by using the same bare, query-less import (e.g. `./my-styles.css`). --\u003e\n\n### `include`/`exclude` (`string[]`)\n\nAbsolute glob patterns.  \nE.g. `include: ['**/src/features/counters/counters.scss']`\n\n### Import flags\n\n#### `?lit`\n\n\u003c!-- This plugin aims to get rid of non-standard import queries.\nHowever, you'll find yourself obliged to use a `CSSResult` in a Node (SSR) setup.\nUntil a leaner solution emerges, you can add the `?lit` flag on a per-file basis.   --\u003e\n\u003c!-- This can be useful if you want to do **server-side-only** stuff with some **client-side**\nleaves deeper in the tree, whereas the `transformationMode` shown above is all or nothing. --\u003e\n\n```ts\nimport myStyles1 from './my-styles-1.css?lit' with { type: 'css' };\n```\n\nOverrides `CSSStyleSheet` to `CSSResult` on a per-file basis.\n\nFor some reasons, like isomorphism, you might want a `CSSResult` on the client side, but it's not needed otherwise.\nLit (on browser) handles those two shapes just fine, without intermediary steps.  \nIt's possible to mix and fit them in the static `styles` of your custom element.  \nAlso, note that hydration alleviates the need for loading the CSS on the client too, hence the `emptyClient` option for that cases.\n\n### SSR considerations with `CSSStyleSheet`\n\nIf no DOM shims are present in your JS server runtime, you'll get a `CSSStyleSheet is not defined`.  \nWith a DOM Shim (like the Lit SSR's one), you'll get a `replaceSync method is not defined`, because the `CSSStyleSheet` global object is empty.  \nSolution: use `CSSResult` here (it is set as the default with SSR).\n\n## Environments\n\n- Vite 5\n- Vite 5 **SSR** (`ssrModuleLoader`)\n- Astro 4 **Client** side JS\n- Astro 4 **Server** side JS\n\nTested with Node 20 (LTS) and 2024 majors browsers.  \nFirefox / Safari / Chromium are all supporting constructable stylesheets.\n\n## TypeScript\n\n## Pre/post processors\n\nSupport all Vite's CSS pipelines and formats (PostCSS, Less, SASS…).\n\n### IDE awareness\n\n```ts\n// ./src/vite-env.d.ts\n// or\n// ./src/env.d.ts\n\n// Add this reference:\n/// \u003creference types=\"vite-plugin-standard-css-modules/css-modules\" /\u003e\n// (Order matters with Astro)\n\n/// \u003creference types=\"vite/client\" /\u003e\n//              (Or `astro/client`)\n```\n\nThat way,\n\n```ts\nimport myElementStyles from './my-element.css' with { type: 'css' };\nimport myElementStyles from './my-element.css?lit' with { type: 'css' };\n```\n\n- `./my-element.css` will be cast as `CSSStyleSheet`\n- `./my-element.css?lit` will be cast as `CSSResult`\n\nYou can also append them manually in your `env.d.ts`, see [css-modules.d.ts](./css-modules.d.ts).\n\n## Demo\n\nCheck out the [demo folder](https://github.com/JulianCataldo/vite-plugin-standard-css-modules).\n\nYou'll find an Astro minimal setup, which works **exactly the same** as with this\n[vite-lit-ssr demo project](https://github.com/vikerman/vite-lit-ssr).\n\nI updated to the latest Lit 3 and Vite 5, and with minor Lit SSR syntax adaption, tested it successfully.\n\nBoth of these setups, Homebrewed Lit SSR and Astro, are using `ssrLoadModuleLoader`.  \nBasically, you'll get an isomorphic experience thanks to Vite internal tooling which is smoothening environment gaps, minus unresolved DOM limitations in Node.\n\n## How it works?\n\n`file.css` redirects to `file.css?raw` which by-pass all specific Vite handling.  \nThen `file.css?inline` is requested and injected back. This means you should get your usual Vite CSS handling at the end (think all the `post-css` stuff).\n\n---\n\nSince the result is handled like any `?raw` imported module with Vite, it's not a \"real\", living CSS module.  \nSee the `rollup-plugin-css-modules` documentation for more details about expected limitations, which are shared conceptually, with `vite-plugin-standard-css-modules`.\n\n## Import Attributes\n\nFor now, attributes are just \"decorative\", and act as a reminder for what is a standard CSS Module and what is\nnot.  \nWhen Vite will support Import Attributes like Rollup and browsers, those flag will be leveraged and no `include`/`exclude` should be needed anymore.\n\n## Improvements\n\n- Support for relative globs in `include`/`exclude`\n\n## Footnotes\n\n100% ESM, **dependency-free**.\n\nYou just need the optional `lit` peer-dependency, if you're using `CSSResult` over the default `CSSStyleSheet`.\n\n---\n\nSee also [rollup-plugin-css-modules](https://www.npmjs.com/package/rollup-plugin-css-modules).  \nIts documentation will bring you insights into the state of this API proposal.\n\n---\n\n**Other projects 👀**…\n\n- [retext-case-police](https://github.com/JulianCataldo/retext-case-police): Check popular names casing. Example: ⚠️ `github` → ✅ `GitHub`.\n- [remark-lint-frontmatter-schema](https://github.com/JulianCataldo/remark-lint-frontmatter-schema): Validate your Markdown **frontmatter** data against a **JSON schema**.\n- [JSON Schema Form Element](https://github.com/json-schema-form-element/jsfe): Effortless forms, with standards.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Find this project useful?**\n\n[![GitHub](https://img.shields.io/badge/Star_me_on_GitHub-222222?logo=github\u0026style=social)](https://github.com/JulianCataldo/vite-plugin-standard-css-modules)\n\n\u003c/div\u003e\n\n---\n\n🔗  [JulianCataldo.com](https://www.juliancataldo.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgracile-web%2Fvite-plugin-standard-css-modules","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgracile-web%2Fvite-plugin-standard-css-modules","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgracile-web%2Fvite-plugin-standard-css-modules/lists"}