vite-plugin-theme-css
v0.5.1
Published
Vite 插件:theme.config → 编译期 SCSS(CSS 变量 + helper)+ 运行时 globalThis.__THEME_CSS__ 深合并
Maintainers
Readme
vite-plugin-theme-css
Vite 插件:一份 theme.config.ts → 编译期 SCSS(CSS 变量 + helper)+ 运行时 JS(globalThis.__THEME_CSS__ 深合并)。
架构要点
| 产物 | 时机 | 数据来源 |
| --- | --- | --- |
| SCSS / CSS 变量定义 | 编译时 | 本插件的 theme.config |
| JS 最终配置 | 运行时 | globalThis.__THEME_CSS__ 深合并(只增/覆盖,不删) |
- CSS 覆盖靠层叠:多包各自带出的
:root/[data-theme]同名变量,后加载覆盖先加载即可;插件不做多源 CSS 合并。 - 变量交付两条路:默认
autoImportVars把已生成的 CSS 注入 HTML<style>(开发/打包一致);关掉后可手动import '@scope/theme-css/vars'走 Sass。helper 始终经additionalData注入,不含顶层:root。 - JS 加载即注册:模块执行时
registerThemeConfig→ merge 进全局;theme/setTheme/getConfig都读写这份 store。适用于「业务 + 已打包组件库」——打包后无法靠 Vite 多插件合并,只能靠全局对象让业务覆盖组件库的 JS 配置。
暂不把「多插件编译期 deepMerge」当主方案;SCSS 绝不能用最终 global 合并结果生成。
安装
pnpm add vite-plugin-theme-css
# 或
npm i vite-plugin-theme-css需配合 Vite >=5;使用 SCSS helper / 手动 @scope/theme-css/vars 时请自行安装 sass。
命名:npm 包名是
vite-plugin-theme-css;用户侧虚拟模块 ID 是@scope/theme-css/@scope/theme-css/vars/@scope/theme-css/scss(二者不同)。
快速开始
1. 创建主题配置
默认读取项目根目录的 theme.config.ts:
import { defineTheme } from 'vite-plugin-theme-css'
export default defineTheme({
themes: {
light: {
text: {
primary: '#111',
secondary: '#666'
},
bg: {
page: '#fff'
}
},
dark: {
text: {
primary: '#f5f5f5',
secondary: '#aaa'
},
bg: {
page: '#111'
}
}
},
common: {
font: {
size: {
h1: '32px',
body: '14px'
}
}
}
})嵌套对象会扁平化为 CSS 变量:
| 配置路径 | CSS 变量 |
| --- | --- |
| themes.light.text.primary | --text-primary |
| common.font.size.h1 | --common-font-size-h1 |
主题变量挂在 :root[data-theme="..."],公共变量挂在 :root(写在生成的 SCSS 里,由 Sass 编译进最终 CSS)。
defineTheme为类型辅助(恒等函数)。配置里调用了defineTheme但未 import 时,插件会自动注入,类似 Vite 的defineConfig。
2. 注册插件
// vite.config.ts
import { defineConfig } from 'vite'
import { themeCss } from 'vite-plugin-theme-css'
export default defineConfig({
plugins: [themeCss()]
})3. 引入两份 SCSS(职责拆开)
| 产物 | 引入方式 | 内容 |
| --- | --- | --- |
| CSS 变量(默认) | autoImportVars: true → HTML <style> | 配置 直接 生成扁平 CSS(不经 Sass,开发/打包一致) |
| @scope/theme-css/vars | 关自动后手动引入 | 配置 → 嵌套 $themes / $common → Sass @each 编译出 CSS 变量 |
| @scope/theme-css/scss | additionalData 自动注入 | 仅 helper(var(--…)),无顶层 CSS |
两条路都只吃本包
theme.config,互不依赖。自动注入是为了免手写、打包稳妥;理想「map → Sass → 变量」走@scope/theme-css/vars。不要两路同时开(会重复,通常无害)。
// 默认无需手写;若 autoImportVars: false:
import '@scope/theme-css/vars'
import './style.scss'vars 生成形态(节选,由 Sass 再编成 :root):
$themes: (
light: (
text: ( primary: "#111", secondary: "#666" ),
bg: ( page: "#fff" )
),
dark: ( ... )
);
$common: (
font: ( size: ( h1: "32px", body: "14px" ) )
);
// …再 @each 展开为 --text-primary 等不要把会 emit
:root的 vars 塞进additionalData:每个 scss 入口都会再打一份变量。
用法
CSS / 内联样式
.card {
color: var(--text-primary);
background: var(--bg-page);
}SCSS
.title {
color: token.theme(text, primary); // var(--text-primary)
font-size: token.common(font, size, h1); // var(--common-font-size-h1)
}
.banner {
@include token.on-theme(dark) {
opacity: 0.9;
}
}| API | 说明 |
| --- | --- |
| token.theme($keys...) | 主题变量 → var(--a-b-c) |
| token.common($keys...) | 公共变量 → var(--common-a-b-c) |
| @include token.on-theme($name) | 在指定主题下生效 |
也可手动导入 helper(一般不必,插件已注入):
@use '@scope/theme-css/scss' as token;关闭 autoImportVars 后,也可在唯一入口 scss 里手动引入:
@use '@scope/theme-css/vars';JS 运行时
import { theme, common, setTheme, getTheme, getConfig } from '@scope/theme-css'
theme('text', 'primary') // 当前主题下合并后的原始值
common('font', 'size', 'h1')
getConfig() // 最终 deepMerge 后的 ThemeConfig
setTheme('dark') // 设置 html[data-theme="dark"]
getTheme() // 'dark'加载 @scope/theme-css 时会立刻把本包 config registerThemeConfig 进 globalThis.__THEME_CSS__。
已打包组件库若也带同一套 runtime,会与业务侧配置在全局上合并;theme() 读到的是合并结果,与 CSS 层叠覆盖语义对齐。
setTheme 默认在主题名为 dark 时同步给 <html> 加上 dark class(可用 syncHtmlDark: false 关闭)。
TypeScript 需引入虚拟模块声明(在 env.d.ts / vite-env.d.ts 中):
/// <reference types="vite-plugin-theme-css/client" />无 Vite 虚拟模块时(组件库打包产物)
./runtime 不提供顶层 theme 函数,用 themeApi 或 createThemeRuntime:
import {
registerThemeConfig,
themeApi,
getConfig,
createThemeRuntime
} from 'vite-plugin-theme-css/runtime'
registerThemeConfig(myBakedConfig, { syncHtmlDark: true })
themeApi.theme('text', 'primary')
getConfig()
// 或一步:注册并拿到同一份共享 API
const { theme, setTheme } = createThemeRuntime(myBakedConfig)插件选项
themeCss({
/** 配置文件路径,默认 './theme.config.ts' */
config: './theme.config.ts',
/** SCSS 命名空间,默认 'token' */
scssNamespace: 'token',
/** 是否同步 html.dark class,默认 true */
syncHtmlDark: true,
/** 排除自动注入 SCSS helper 的文件 */
exclude: [/node_modules/],
// 或: (filename) => filename.includes('legacy')
/** 是否自动把 CSS 变量注入 HTML(<style>),默认 true;开发/打包一致 */
autoImportVars: true
})虚拟模块
| 模块 ID | 内容 |
| --- | --- |
| (HTML <style>) | autoImportVars:配置直接生成的扁平 CSS |
| @scope/theme-css/vars | 嵌套 $themes/$common,经 Sass 展开变量 |
| @scope/theme-css/scss | 仅 helper(additionalData 注入) |
| @scope/theme-css | 运行时 API(加载即 register;theme / common / setTheme / getTheme / getConfig) |
热更新
修改 theme.config.ts 后会重新生成 SCSS / runtime-data 并触发页面 full-reload。
开发
pnpm test # 单元测试
pnpm build # 构建 dist
pnpm play # playgroundLicense
MIT
