{"id":15011207,"url":"https://github.com/unplugin/unplugin-vue-cssvars","last_synced_at":"2025-04-05T11:11:16.122Z","repository":{"id":143262072,"uuid":"611173610","full_name":"unplugin/unplugin-vue-cssvars","owner":"unplugin","description":"🌀 A vue plugin that allows you to use vue's CSSVars feature in css files","archived":false,"fork":false,"pushed_at":"2025-04-01T13:09:21.000Z","size":1325,"stargazers_count":112,"open_issues_count":13,"forks_count":21,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-01T20:14:37.906Z","etag":null,"topics":["css","cssvars","less","rollup","rspack","sass","unplugin","vite","vue","vue3","webpack","webpack4","webpack5"],"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/unplugin.png","metadata":{"files":{"readme":"README.ZH-CN.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":"2023-03-08T09:19:02.000Z","updated_at":"2025-01-17T16:07:01.000Z","dependencies_parsed_at":"2023-09-08T08:18:01.885Z","dependency_job_id":"9cee637c-e03f-444d-9d1b-a3ebe6e5cf29","html_url":"https://github.com/unplugin/unplugin-vue-cssvars","commit_stats":{"total_commits":315,"total_committers":7,"mean_commits":45.0,"dds":0.5809523809523809,"last_synced_commit":"ce2400fe79af572aa59db10241e23705294ec504"},"previous_names":["unplugin/unplugin-vue-cssvars","baiwusanyu-c/unplugin-vue-cssvars"],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unplugin%2Funplugin-vue-cssvars","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unplugin%2Funplugin-vue-cssvars/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unplugin%2Funplugin-vue-cssvars/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unplugin%2Funplugin-vue-cssvars/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unplugin","download_url":"https://codeload.github.com/unplugin/unplugin-vue-cssvars/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247242678,"owners_count":20907134,"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":["css","cssvars","less","rollup","rspack","sass","unplugin","vite","vue","vue3","webpack","webpack4","webpack5"],"created_at":"2024-09-24T19:39:41.896Z","updated_at":"2025-04-05T11:11:16.103Z","avatar_url":"https://github.com/unplugin.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/baiwusanyu-c/unplugin-vue-cssvars/master/public/logo.png\" /\u003e\n\u003c/p\u003e\n\u003ch1 align=\"center\"\u003e\nunplugin-vue-cssvars\n\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n🌀 一个 vue3 的插件能够能让你在 css 文件中使用 CSSVars 特性\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/unplugin/unplugin-vue-cssvars/blob/master/README.md\" target=\"_blank\"\u003eEnglish\u003c/a\u003e | 中文\n\u003c/p\u003e\n\n## Feature\n\n* 🧩 它是一个 vue 的功能扩展，让你能够在 css 文件中使用 v-bind\n* 🌈 支持全平台打包工具构建（vite、webpack）\n* ⛰ 支持 css, sass, scss, less, stylus\n*  ⚡ 支持热更新\n\n## Core Strategy\n1. 在使用开发服务器时，`unplugin-vue-cssvars`会从组件开始分析引用的css文件，\n并在`@vitejs/plugin-vue` 的转换代码中进行注入样式\n2. 在打包时`unplugin-vue-cssvars`会从组件开始分析引用的css文件，并将其注入到\nsfc 中，别担心会产生多余的代码，打包工具（例如 vite）会自动处理它。\n\n## Install\n\n```bash\nnpm i unplugin-vue-cssvars -D\n```\n或\n```bash\nyarn add unplugin-vue-cssvars -D\n```\n或\n```bash\npnpm add unplugin-vue-cssvars -D\n```\n\n## Usage\n1. 使用插件并配置\n\u003cdetails\u003e\n\u003csummary\u003eVite\u003c/summary\u003e\n\n```ts\n// vite.config.ts\nimport { defineConfig } from 'vite'\nimport { viteVueCSSVars } from 'unplugin-vue-cssvars'\nimport vue from '@vitejs/plugin-vue'\nimport type { PluginOption } from 'vite'\nexport default defineConfig({\n  plugins: [\n    vue(),\n    viteVueCSSVars({\n      include: [/.vue/],\n      includeCompile: ['**/**.scss'],\n      server: false,\n    }) as PluginOption,\n  ],\n})\n```\n\n\u003c/details\u003e\n\u003cbr\u003e\n\u003cdetails\u003e\n\u003csummary\u003eRollup\u003c/summary\u003e\n\n```ts\n// rollup.config.js\nimport { rollupVueCSSVars } from 'unplugin-vue-cssvars'\nexport default {\n  plugins: [\n    rollupVueCSSVars(/* options */),\n  ],\n}\n```\n\n\u003c/details\u003e\n\u003cbr\u003e\n\u003cdetails\u003e\n\u003csummary\u003eWebpack\u003c/summary\u003e\n\n```ts\n// webpack.config.js\nmodule.exports = {\n  /* ... */\n  plugins: [\n    require('unplugin-vue-cssvars').webpackVueCSSVars({ /* options */ }),\n  ],\n}\n```\n\u003c/details\u003e\n\u003cbr\u003e\n\u003cdetails\u003e\n\u003csummary\u003eVue CLI\u003c/summary\u003e\n\n```ts\n// vue.config.js\nmodule.exports = {\n  configureWebpack: {\n    plugins: [\n      require('unplugin-vue-cssvars').webpackVueCSSVars({ /* options */ }),\n    ],\n  },\n}\n```\n\n\u003c/details\u003e\n\u003cbr\u003e\n\u003cdetails\u003e\n\u003csummary\u003eESBuild\u003c/summary\u003e\n\n```ts\n// esbuild.config.js\nimport { build } from 'esbuild'\nimport { esbuildVueCSSVars } from 'unplugin-vue-cssvars'\n\nbuild({\n  plugins: [esbuildVueCSSVars(/* options */)],\n})\n```\n\u003c/details\u003e\n\n2. 使用 `v-bind-m`\n```\n// foo.css\n.foo{\n   color: v-bind-m(fontColor)\n}\n```\n3. 使用别名   \n\n例如你有以下项目结构：  \n\n![img.png](public/img.png)\n\n ```\n// App.vue\n\u003ctemplate\u003e\n  \u003cdiv class=\"scss\"\u003e\n    app\n  \u003c/div\u003e\n\u003c/template\u003e\n\n\u003cstyle lang=\"scss\" scoped\u003e\n@import '@/assets/scss/mixin';\n\u003c/style\u003e\n\n```\n\n那么你可以这样配置\n\n```\n// vite.config.ts\nimport { resolve } from 'path'\nimport { defineConfig } from 'vite'\nimport vue from '@vitejs/plugin-vue'\nimport { viteVueCSSVars } from '../dist'\nexport default defineConfig({\n  resolve: {\n    alias: {\n      '@': resolve(__dirname, './src'),\n    },\n  },\n  plugins: [\n    vue(),\n    viteVueCSSVars({\n      include: [/.vue/],\n      includeCompile: ['**/**.scss'],\n      alias: {\n        '@': resolve(__dirname, './src'),\n      },\n    }),\n  ],\n})\n\n````\n\n## Option\n\n```typescript\nexport interface Options {\n  /**\n   * 需要转换的路径，默认是项目根目录\n   * @default process.cwd()\n   */\n  rootDir?: string\n   \n  /**\n   * 需要转换的文件名后缀列表（目前只支持.vue）RegExp or glob\n   */\n  include?: FilterPattern\n\n  /**\n   * 不需要转换的文件名后缀列表（目前只支持.vue）RegExp or glob\n   */\n  exclude?: FilterPattern\n\n   /**\n    * 选择需要处理编译的文件，默认是css\n    * 例如：如果你想要处理.scss文件，那么你可以传入 ['** /**.sass']\n    * @property { ['** /**.css', '** /**.less', '** /**.scss', '** /**.sass', '** /**.styl'] }\n    * @default ['** /**.css']\n    */\n   includeCompile?: Array\u003cstring\u003e\n   \n   /**\n    * 标记是否为开发服务器使用\n    * 因为 unplugin-vue-cssvars 在开发服务器上和打包中使用了不同策略,\n    * vite 中如果不传递它，unplugin-vue-cssvars 将自动识别 config 的 command 来决定 server 值\n    * @default true\n    */\n   server?: boolean\n\n   /**\n    * 别名\n    * @default undefined\n    */\n   alias?: Record\u003cstring, string\u003e\n\n}\n```\n\n## Tips\n\n### ● 转换分析时的约定规则\n1. `sfc` 中，如果 `@import` 指定了后缀，则根据后缀的文件进行转换分析，否则根据当前 `style` 标签的 `lang` 属性（默认 `css` ）进行转换分析\n2. `css` 中规则：`css` 文件只能引用 `css` 文件，只会解析 `css` 后缀的文件。\n3. `scss`、`less`、`stylus` 中规则：`scss`、`less`、`stylus` 文件可以引用 `css` 文件、以及对应的 `scss` 或 `less` 文件或 `stylus` 文件，  \n   优先对预处理器后缀的文件进行转换分析，如果文件不存在，则对其 `css` 文件进行分析\n\n### ● sfc 中变量提取规则\n1. 对于 `script setup`, `unplugin-vue-cssvars` 会提取所有变量进行匹配。\n````\n\u003cscript setup\u003e\n    const color = 'red'\n\u003c/script\u003e\n````\n2. 对于 `composition api`, `unplugin-vue-cssvars` 会提取 `setup` 函数返回变量进行匹配。\n````\n\u003cscript\u003e\n import { defineComponent } from 'vue'\n export default defineComponent( {\n   setup(){\n       const color = 'red'\n       return {\n          color\n       }\n   }\n})\n\u003c/script\u003e\n````\n3. 对于 `options api`, `unplugin-vue-cssvars` 会提取 `data` 函数返回变量进行匹配。\n````\n\u003cscript\u003e\n export default {\n   data(){\n       const color = 'red'\n       return {\n          color\n       }\n   }\n}\n\u003c/script\u003e\n````\n4. 对于普通的 `script`, `unplugin-vue-cssvars` 会提取所有变量进行匹配。\n````\n\u003cscript\u003e\n    const color = 'red'\n\u003c/script\u003e\n````\n\n### ● sfc 中变量冲突规则\n1. `sfc` 中有 `options api` 与 `composition api`, 所有变量会进行合并\n变量出现冲突以后面出现的（比如先写了 `options api`，后写 `composition api`，以 `composition api` 优先）优先\n2. `sfc` 中有  `script setup`、`options api` 与 `composition api`,  所有变量会进行合并，变量出现冲突以`script setup`优先\n3. `sfc` 中普通的 `script`，不会与`options api` 、 `composition api`同时存在\n4. `sfc` 中普通的 `script`若存在，则必存在`script setup`\n5. `sfc` 中普通的 `script`与 `script setup` 所有变量会进行合并,变量出现冲突以`script setup`优先\n\n### ● 样式提升后的优先级\n1. 从 `sfc` 开始，分析 `style` 标签中引用的 `css` 文件，按照 `css` 文件中的引用顺序，深度优先依次提升并注入到 `sfc` 中。\n2. 注入到 `sfc` 后，其优先级完全由 `@vue/compiler-dom` 的编译器决定。\n\n\n## Thanks\n* [vue](https://github.com/vuejs/core)\n* [vite](https://github.com/vitejs/vite)\n* [unplugin](https://github.com/unjs/unplugin)\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funplugin%2Funplugin-vue-cssvars","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funplugin%2Funplugin-vue-cssvars","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funplugin%2Funplugin-vue-cssvars/lists"}