vite-plugin-theme-css 0.1.0

package/README.md

@@ -0,0 +1,202 @@
+# vite-plugin-theme-css
+
+Vite 插件：用一份主题配置生成 CSS 变量、SCSS helper 与 JS 运行时，支持多主题切换与热更新。
+
+## 安装
+
+```bash
+pnpm add vite-plugin-theme-css
+# 或
+npm i vite-plugin-theme-css
+```
+
+需配合 Vite `>=5`，若使用 SCSS helper，请自行安装 `sass`。
+
+## 快速开始
+
+### 1. 创建主题配置
+
+默认读取项目根目录的 `theme.config.ts`：
+
+```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`。
+
+> `defineTheme` 为类型辅助（恒等函数）。配置里调用了 `defineTheme` 但未 import 时，插件会自动注入，类似 Vite 的 `defineConfig`。
+
+### 2. 注册插件
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { themeCss } from 'vite-plugin-theme-css'
+
+export default defineConfig({
+  plugins: [themeCss()]
+})
+```
+
+### 3. 引入 CSS 变量
+
+在入口文件中导入虚拟 CSS：
+
+```ts
+import 'virtual:theme-css/css'
+```
+
+生成示例：
+
+```css
+:root {
+  --common-font-size-h1: 32px;
+  --common-font-size-body: 14px;
+}
+
+:root[data-theme="light"] {
+  --text-primary: #111;
+  --text-secondary: #666;
+  --bg-page: #fff;
+}
+
+:root[data-theme="dark"] {
+  --text-primary: #f5f5f5;
+  --text-secondary: #aaa;
+  --bg-page: #111;
+}
+```
+
+## 用法
+
+### CSS / 内联样式
+
+```css
+.card {
+  color: var(--text-primary);
+  background: var(--bg-page);
+}
+```
+
+### SCSS
+
+插件会通过 `css.preprocessorOptions.scss.additionalData` 自动注入 helper（命名空间默认 `token`），可直接使用：
+
+```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)` | 在指定主题下生效 |
+
+也可手动导入：
+
+```scss
+@use 'virtual:theme-css/scss' as token;
+```
+
+### JS 运行时
+
+```ts
+import { theme, common, setTheme, getTheme } from '@scope/theme-css'
+
+theme('text', 'primary') // 当前主题下的原始值，如 '#111'
+common('font', 'size', 'h1') // '32px'
+
+setTheme('dark') // 设置 html[data-theme="dark"]
+getTheme() // 'dark'
+```
+
+`setTheme` 默认在主题名为 `dark` 时同步给 `<html>` 加上 `dark` class（可用 `syncHtmlDark: false` 关闭）。
+
+## 插件选项
+
+```ts
+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')
+})
+```
+
+## 虚拟模块
+
+| 模块 ID | 内容 |
+| --- | --- |
+| `virtual:theme-css/css` | 生成的 CSS 变量 |
+| `virtual:theme-css/scss` | SCSS helper（`theme` / `common` / `on-theme`） |
+| `@scope/theme-css` | 运行时 API（`theme` / `common` / `setTheme` / `getTheme`） |
+
+## 热更新
+
+修改 `theme.config.ts` 后会重新生成上述模块并触发页面 full-reload。
+
+## 开发
+
+```bash
+pnpm test        # 单元测试
+pnpm build       # 构建 dist
+```
+
+## License
+
+MIT

package/dist/defineTheme.d.ts

@@ -0,0 +1,3 @@
+import type { ThemeConfig } from './types';
+/** 类型辅助，运行时恒等返回 */
+export declare function defineTheme<T extends ThemeConfig>(config: T): T;

package/dist/generate/css/index.d.ts

@@ -0,0 +1,5 @@
+import type { ThemeConfig } from '../../types';
+/**
+ * 根据配置生成 CSS 变量字符串
+ */
+export declare const generateThemeCss: (config: ThemeConfig) => string;

package/dist/generate/js/index.d.ts

@@ -0,0 +1,8 @@
+import type { ThemeConfig } from '../../types';
+export interface JsDataOptions {
+    syncHtmlDark: boolean;
+}
+/**
+ * 只生成 JS 配置数据虚拟模块，不含运行时逻辑。
+ */
+export declare function generateJs(config: ThemeConfig, options: JsDataOptions): string;

package/dist/generate/scss/index.d.ts

@@ -0,0 +1,2 @@
+/** 返回 SCSS helper 模块内容（helper.scss 原文） */
+export declare const generateScssHelper: () => string;

package/dist/index.cjs

@@ -0,0 +1,306 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  createThemeRuntime: () => createThemeRuntime,
+  defineTheme: () => defineTheme,
+  themeCss: () => themeCss
+});
+module.exports = __toCommonJS(src_exports);
+var import_node_fs = require("fs");
+var import_node_path = __toESM(require("path"), 1);
+var import_node_url = require("url");
+var import_node_module = require("module");
+var import_jiti = require("jiti");
+
+// src/types.ts
+var defaultOptions = {
+  config: "./theme.config.ts",
+  scssNamespace: "token",
+  syncHtmlDark: true,
+  exclude: []
+};
+
+// src/utils/flatten.ts
+var flattenTokens = (obj, prefix = "") => {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const newKey = prefix ? `${prefix}-${key}` : key;
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      Object.assign(result, flattenTokens(value, newKey));
+    } else {
+      result[newKey] = String(value);
+    }
+  }
+  return result;
+};
+
+// src/generate/css/index.ts
+var generateThemeCss = (config) => {
+  const { themes, common } = config;
+  const lines = [];
+  if (common) {
+    const flatCommon = flattenTokens(common, "common");
+    lines.push(":root {");
+    for (const [key, value] of Object.entries(flatCommon)) {
+      lines.push(`  --${key}: ${value};`);
+    }
+    lines.push("}");
+  }
+  for (const [themeName, tokens] of Object.entries(themes)) {
+    const flatTokens = flattenTokens(tokens);
+    lines.push(`:root[data-theme="${themeName}"] {`);
+    for (const [key, value] of Object.entries(flatTokens)) {
+      lines.push(`  --${key}: ${value};`);
+    }
+    lines.push("}");
+  }
+  return lines.join("\n");
+};
+
+// src/generate/scss/helper.scss
+var helper_default = `// \u5185\u90E8\u5DE5\u5177\uFF1A\u62FC\u63A5\u591A\u4E2A key\r
+@function _join-keys($keys...) {\r
+  $result: '';\r
+  @each $key in $keys {\r
+    @if $result == '' {\r
+      $result: $key;\r
+    } @else {\r
+      $result: #{$result}-#{$key};\r
+    }\r
+  }\r
+  @return $result;\r
+}\r
+\r
+// \u83B7\u53D6\u4E3B\u9898\u53D8\u91CF\uFF1Atoken.theme(text, primary) -> var(--text-primary)\r
+@function theme($keys...) {\r
+  @return var(--#{_join-keys($keys...)});\r
+}\r
+\r
+// \u83B7\u53D6\u516C\u5171\u53D8\u91CF\uFF1Atoken.common(font, size, h1) -> var(--common-font-size-h1)\r
+@function common($keys...) {\r
+  @return var(--common-#{_join-keys($keys...)});\r
+}\r
+\r
+// \u7279\u5B9A\u4E3B\u9898\u9009\u62E9\u5668\uFF1A@include token.on-theme(dark) { ... }\r
+@mixin on-theme($theme) {\r
+  :root[data-theme="#{$theme}"] & {\r
+    @content;\r
+  }\r
+}\r
+`;
+
+// src/generate/scss/index.ts
+var generateScssHelper = () => helper_default;
+
+// src/generate/js/index.ts
+function generateJs(config, options) {
+  return `export const config = ${JSON.stringify(config, null, 2)}
+export const options = ${JSON.stringify(options)}
+`;
+}
+
+// src/defineTheme.ts
+function defineTheme(config) {
+  return config;
+}
+
+// src/runtime/index.ts
+function getByPath(obj, keys) {
+  return keys.reduce((acc, key) => {
+    if (acc && typeof acc === "object" && key in acc) {
+      return acc[key];
+    }
+    return void 0;
+  }, obj);
+}
+function createThemeRuntime(config, options = {}) {
+  const syncHtmlDark = options.syncHtmlDark ?? true;
+  let currentTheme = typeof document !== "undefined" && document.documentElement.dataset.theme || "light";
+  return {
+    theme(...keys) {
+      const themeTokens = config.themes?.[currentTheme] ?? {};
+      const value = getByPath(themeTokens, keys);
+      return value !== void 0 ? String(value) : "";
+    },
+    common(...keys) {
+      const value = getByPath(config.common ?? {}, keys);
+      return value !== void 0 ? String(value) : "";
+    },
+    setTheme(name) {
+      currentTheme = name;
+      if (typeof document !== "undefined") {
+        document.documentElement.dataset.theme = name;
+        if (syncHtmlDark) {
+          document.documentElement.classList.toggle("dark", name === "dark");
+        }
+      }
+    },
+    getTheme() {
+      return currentTheme;
+    }
+  };
+}
+
+// src/index.ts
+var import_meta = {};
+var require2 = (0, import_node_module.createRequire)(import_meta.url);
+var babelTransform = (0, import_node_module.createRequire)(require2.resolve("jiti/package.json"))("./dist/babel.cjs");
+var VIRTUAL_CSS_ID = "virtual:theme-css/css";
+var VIRTUAL_CSS_RESOLVED = "\0virtual:theme-css.css";
+var VIRTUAL_SCSS_ID = "virtual:theme-css/scss";
+var VIRTUAL_SCSS_RESOLVED = "\0virtual:theme-css.scss";
+var VIRTUAL_RUNTIME_ID = "@scope/theme-css";
+var VIRTUAL_RUNTIME_DATA_ID = "virtual:theme-css/runtime-data";
+var VIRTUAL_RUNTIME_DATA_RESOLVED = "\0virtual:theme-css/runtime-data";
+function resolveRuntimeEntryPath() {
+  const here = import_node_path.default.dirname((0, import_node_url.fileURLToPath)(import_meta.url));
+  const distEntry = import_node_path.default.join(here, "runtime-entry.mjs");
+  if ((0, import_node_fs.existsSync)(distEntry)) return distEntry;
+  return import_node_path.default.join(here, "runtime", "virtual-entry.ts");
+}
+function themeCss(options = {}) {
+  const resolvedOptions = { ...defaultOptions, ...options };
+  const { config: configPath, scssNamespace, syncHtmlDark, exclude } = resolvedOptions;
+  let viteConfig;
+  let themeConfig;
+  let cssContent = "";
+  let scssHelperContent = "";
+  let runtimeDataContent = "";
+  const runtimeEntryPath = resolveRuntimeEntryPath();
+  async function loadConfigAndGenerate() {
+    const jiti = (0, import_jiti.createJiti)(import_meta.url, {
+      interopDefault: true,
+      transform: (opts) => {
+        let { source } = opts;
+        const usesDefineTheme = /\bdefineTheme\s*\(/.test(source);
+        const hasBinding = /\bimport\s[\s\S]*?\bdefineTheme\b/.test(source) || /\b(?:const|let|var|function)\s+defineTheme\b/.test(source);
+        if (usesDefineTheme && !hasBinding) {
+          source = `const defineTheme = (c) => c;
+${source}`;
+        }
+        return babelTransform({ ...opts, source });
+      }
+    });
+    const mod = await jiti.import(import_node_path.default.resolve(configPath));
+    themeConfig = mod.default;
+    cssContent = generateThemeCss(themeConfig);
+    scssHelperContent = generateScssHelper();
+    runtimeDataContent = generateJs(themeConfig, { syncHtmlDark });
+  }
+  return {
+    name: "vite-plugin-theme-css",
+    async configResolved(config) {
+      viteConfig = config;
+      await loadConfigAndGenerate();
+    },
+    resolveId(id) {
+      switch (id) {
+        case VIRTUAL_CSS_ID:
+          return VIRTUAL_CSS_RESOLVED;
+        case VIRTUAL_SCSS_ID:
+          return VIRTUAL_SCSS_RESOLVED;
+        case VIRTUAL_RUNTIME_ID:
+          return runtimeEntryPath;
+        case VIRTUAL_RUNTIME_DATA_ID:
+          return VIRTUAL_RUNTIME_DATA_RESOLVED;
+        default:
+          return null;
+      }
+    },
+    load(id) {
+      switch (id) {
+        case VIRTUAL_CSS_RESOLVED:
+          return cssContent;
+        case VIRTUAL_SCSS_RESOLVED:
+          return scssHelperContent;
+        case VIRTUAL_RUNTIME_DATA_RESOLVED:
+          return runtimeDataContent;
+        default:
+          return null;
+      }
+    },
+    config(userConfig) {
+      const scssOptions = userConfig.css?.preprocessorOptions?.scss ?? {};
+      const userAdditionalData = scssOptions.additionalData;
+      const ourPrefix = `@use "${VIRTUAL_SCSS_ID}" as ${scssNamespace};
+`;
+      const wrappedAdditionalData = async (source, filename) => {
+        if (filename.includes("virtual:theme-css")) {
+          return typeof userAdditionalData === "function" ? await userAdditionalData(source, filename) : userAdditionalData ?? "";
+        }
+        const shouldExclude = Array.isArray(exclude) ? exclude.some((rule) => {
+          if (typeof rule === "string") return filename.includes(rule);
+          if (rule instanceof RegExp) return rule.test(filename);
+          return false;
+        }) : typeof exclude === "function" ? exclude(filename) : false;
+        if (shouldExclude) {
+          return typeof userAdditionalData === "function" ? await userAdditionalData(source, filename) : userAdditionalData ?? "";
+        }
+        const userContent = typeof userAdditionalData === "function" ? await userAdditionalData(source, filename) : userAdditionalData ?? "";
+        return ourPrefix + userContent;
+      };
+      return {
+        css: {
+          preprocessorOptions: {
+            scss: {
+              ...scssOptions,
+              additionalData: wrappedAdditionalData
+            }
+          }
+        }
+      };
+    },
+    async handleHotUpdate(ctx) {
+      const configAbsPath = import_node_path.default.resolve(configPath);
+      if (ctx.file === configAbsPath) {
+        await loadConfigAndGenerate();
+        const moduleGraph = ctx.server.moduleGraph;
+        for (const id of [
+          VIRTUAL_CSS_RESOLVED,
+          VIRTUAL_SCSS_RESOLVED,
+          VIRTUAL_RUNTIME_DATA_RESOLVED,
+          runtimeEntryPath
+        ]) {
+          const mod = moduleGraph.getModuleById(id);
+          if (mod) moduleGraph.invalidateModule(mod);
+        }
+        ctx.server.ws.send({ type: "full-reload" });
+      }
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createThemeRuntime,
+  defineTheme,
+  themeCss
+});

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import type { Plugin } from 'vite';
+import type { ThemeCssOptions } from './types';
+export declare function themeCss(options?: ThemeCssOptions): Plugin;
+export type { ThemeCssOptions, ThemeConfig } from './types';
+export type { ThemeRuntime, ThemeRuntimeOptions } from './runtime';
+export { defineTheme } from './defineTheme';
+export { createThemeRuntime } from './runtime';

package/dist/index.mjs

@@ -0,0 +1,268 @@
+// src/index.ts
+import { existsSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { createRequire } from "module";
+import { createJiti } from "jiti";
+
+// src/types.ts
+var defaultOptions = {
+  config: "./theme.config.ts",
+  scssNamespace: "token",
+  syncHtmlDark: true,
+  exclude: []
+};
+
+// src/utils/flatten.ts
+var flattenTokens = (obj, prefix = "") => {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const newKey = prefix ? `${prefix}-${key}` : key;
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      Object.assign(result, flattenTokens(value, newKey));
+    } else {
+      result[newKey] = String(value);
+    }
+  }
+  return result;
+};
+
+// src/generate/css/index.ts
+var generateThemeCss = (config) => {
+  const { themes, common } = config;
+  const lines = [];
+  if (common) {
+    const flatCommon = flattenTokens(common, "common");
+    lines.push(":root {");
+    for (const [key, value] of Object.entries(flatCommon)) {
+      lines.push(`  --${key}: ${value};`);
+    }
+    lines.push("}");
+  }
+  for (const [themeName, tokens] of Object.entries(themes)) {
+    const flatTokens = flattenTokens(tokens);
+    lines.push(`:root[data-theme="${themeName}"] {`);
+    for (const [key, value] of Object.entries(flatTokens)) {
+      lines.push(`  --${key}: ${value};`);
+    }
+    lines.push("}");
+  }
+  return lines.join("\n");
+};
+
+// src/generate/scss/helper.scss
+var helper_default = `// \u5185\u90E8\u5DE5\u5177\uFF1A\u62FC\u63A5\u591A\u4E2A key\r
+@function _join-keys($keys...) {\r
+  $result: '';\r
+  @each $key in $keys {\r
+    @if $result == '' {\r
+      $result: $key;\r
+    } @else {\r
+      $result: #{$result}-#{$key};\r
+    }\r
+  }\r
+  @return $result;\r
+}\r
+\r
+// \u83B7\u53D6\u4E3B\u9898\u53D8\u91CF\uFF1Atoken.theme(text, primary) -> var(--text-primary)\r
+@function theme($keys...) {\r
+  @return var(--#{_join-keys($keys...)});\r
+}\r
+\r
+// \u83B7\u53D6\u516C\u5171\u53D8\u91CF\uFF1Atoken.common(font, size, h1) -> var(--common-font-size-h1)\r
+@function common($keys...) {\r
+  @return var(--common-#{_join-keys($keys...)});\r
+}\r
+\r
+// \u7279\u5B9A\u4E3B\u9898\u9009\u62E9\u5668\uFF1A@include token.on-theme(dark) { ... }\r
+@mixin on-theme($theme) {\r
+  :root[data-theme="#{$theme}"] & {\r
+    @content;\r
+  }\r
+}\r
+`;
+
+// src/generate/scss/index.ts
+var generateScssHelper = () => helper_default;
+
+// src/generate/js/index.ts
+function generateJs(config, options) {
+  return `export const config = ${JSON.stringify(config, null, 2)}
+export const options = ${JSON.stringify(options)}
+`;
+}
+
+// src/defineTheme.ts
+function defineTheme(config) {
+  return config;
+}
+
+// src/runtime/index.ts
+function getByPath(obj, keys) {
+  return keys.reduce((acc, key) => {
+    if (acc && typeof acc === "object" && key in acc) {
+      return acc[key];
+    }
+    return void 0;
+  }, obj);
+}
+function createThemeRuntime(config, options = {}) {
+  const syncHtmlDark = options.syncHtmlDark ?? true;
+  let currentTheme = typeof document !== "undefined" && document.documentElement.dataset.theme || "light";
+  return {
+    theme(...keys) {
+      const themeTokens = config.themes?.[currentTheme] ?? {};
+      const value = getByPath(themeTokens, keys);
+      return value !== void 0 ? String(value) : "";
+    },
+    common(...keys) {
+      const value = getByPath(config.common ?? {}, keys);
+      return value !== void 0 ? String(value) : "";
+    },
+    setTheme(name) {
+      currentTheme = name;
+      if (typeof document !== "undefined") {
+        document.documentElement.dataset.theme = name;
+        if (syncHtmlDark) {
+          document.documentElement.classList.toggle("dark", name === "dark");
+        }
+      }
+    },
+    getTheme() {
+      return currentTheme;
+    }
+  };
+}
+
+// src/index.ts
+var require2 = createRequire(import.meta.url);
+var babelTransform = createRequire(require2.resolve("jiti/package.json"))("./dist/babel.cjs");
+var VIRTUAL_CSS_ID = "virtual:theme-css/css";
+var VIRTUAL_CSS_RESOLVED = "\0virtual:theme-css.css";
+var VIRTUAL_SCSS_ID = "virtual:theme-css/scss";
+var VIRTUAL_SCSS_RESOLVED = "\0virtual:theme-css.scss";
+var VIRTUAL_RUNTIME_ID = "@scope/theme-css";
+var VIRTUAL_RUNTIME_DATA_ID = "virtual:theme-css/runtime-data";
+var VIRTUAL_RUNTIME_DATA_RESOLVED = "\0virtual:theme-css/runtime-data";
+function resolveRuntimeEntryPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const distEntry = path.join(here, "runtime-entry.mjs");
+  if (existsSync(distEntry)) return distEntry;
+  return path.join(here, "runtime", "virtual-entry.ts");
+}
+function themeCss(options = {}) {
+  const resolvedOptions = { ...defaultOptions, ...options };
+  const { config: configPath, scssNamespace, syncHtmlDark, exclude } = resolvedOptions;
+  let viteConfig;
+  let themeConfig;
+  let cssContent = "";
+  let scssHelperContent = "";
+  let runtimeDataContent = "";
+  const runtimeEntryPath = resolveRuntimeEntryPath();
+  async function loadConfigAndGenerate() {
+    const jiti = createJiti(import.meta.url, {
+      interopDefault: true,
+      transform: (opts) => {
+        let { source } = opts;
+        const usesDefineTheme = /\bdefineTheme\s*\(/.test(source);
+        const hasBinding = /\bimport\s[\s\S]*?\bdefineTheme\b/.test(source) || /\b(?:const|let|var|function)\s+defineTheme\b/.test(source);
+        if (usesDefineTheme && !hasBinding) {
+          source = `const defineTheme = (c) => c;
+${source}`;
+        }
+        return babelTransform({ ...opts, source });
+      }
+    });
+    const mod = await jiti.import(path.resolve(configPath));
+    themeConfig = mod.default;
+    cssContent = generateThemeCss(themeConfig);
+    scssHelperContent = generateScssHelper();
+    runtimeDataContent = generateJs(themeConfig, { syncHtmlDark });
+  }
+  return {
+    name: "vite-plugin-theme-css",
+    async configResolved(config) {
+      viteConfig = config;
+      await loadConfigAndGenerate();
+    },
+    resolveId(id) {
+      switch (id) {
+        case VIRTUAL_CSS_ID:
+          return VIRTUAL_CSS_RESOLVED;
+        case VIRTUAL_SCSS_ID:
+          return VIRTUAL_SCSS_RESOLVED;
+        case VIRTUAL_RUNTIME_ID:
+          return runtimeEntryPath;
+        case VIRTUAL_RUNTIME_DATA_ID:
+          return VIRTUAL_RUNTIME_DATA_RESOLVED;
+        default:
+          return null;
+      }
+    },
+    load(id) {
+      switch (id) {
+        case VIRTUAL_CSS_RESOLVED:
+          return cssContent;
+        case VIRTUAL_SCSS_RESOLVED:
+          return scssHelperContent;
+        case VIRTUAL_RUNTIME_DATA_RESOLVED:
+          return runtimeDataContent;
+        default:
+          return null;
+      }
+    },
+    config(userConfig) {
+      const scssOptions = userConfig.css?.preprocessorOptions?.scss ?? {};
+      const userAdditionalData = scssOptions.additionalData;
+      const ourPrefix = `@use "${VIRTUAL_SCSS_ID}" as ${scssNamespace};
+`;
+      const wrappedAdditionalData = async (source, filename) => {
+        if (filename.includes("virtual:theme-css")) {
+          return typeof userAdditionalData === "function" ? await userAdditionalData(source, filename) : userAdditionalData ?? "";
+        }
+        const shouldExclude = Array.isArray(exclude) ? exclude.some((rule) => {
+          if (typeof rule === "string") return filename.includes(rule);
+          if (rule instanceof RegExp) return rule.test(filename);
+          return false;
+        }) : typeof exclude === "function" ? exclude(filename) : false;
+        if (shouldExclude) {
+          return typeof userAdditionalData === "function" ? await userAdditionalData(source, filename) : userAdditionalData ?? "";
+        }
+        const userContent = typeof userAdditionalData === "function" ? await userAdditionalData(source, filename) : userAdditionalData ?? "";
+        return ourPrefix + userContent;
+      };
+      return {
+        css: {
+          preprocessorOptions: {
+            scss: {
+              ...scssOptions,
+              additionalData: wrappedAdditionalData
+            }
+          }
+        }
+      };
+    },
+    async handleHotUpdate(ctx) {
+      const configAbsPath = path.resolve(configPath);
+      if (ctx.file === configAbsPath) {
+        await loadConfigAndGenerate();
+        const moduleGraph = ctx.server.moduleGraph;
+        for (const id of [
+          VIRTUAL_CSS_RESOLVED,
+          VIRTUAL_SCSS_RESOLVED,
+          VIRTUAL_RUNTIME_DATA_RESOLVED,
+          runtimeEntryPath
+        ]) {
+          const mod = moduleGraph.getModuleById(id);
+          if (mod) moduleGraph.invalidateModule(mod);
+        }
+        ctx.server.ws.send({ type: "full-reload" });
+      }
+    }
+  };
+}
+export {
+  createThemeRuntime,
+  defineTheme,
+  themeCss
+};

package/dist/runtime/index.d.ts

@@ -0,0 +1,7 @@
+import type { ThemeConfig } from '../types';
+import type { ThemeRuntime, ThemeRuntimeOptions } from './types';
+/**
+ * 创建主题运行时 API。虚拟模块只负责注入 config，逻辑写在这里。
+ */
+export declare function createThemeRuntime(config: ThemeConfig, options?: ThemeRuntimeOptions): ThemeRuntime;
+export type { ThemeRuntime, ThemeRuntimeOptions };

package/dist/runtime/types/index.d.ts

@@ -0,0 +1,9 @@
+export interface ThemeRuntimeOptions {
+    syncHtmlDark?: boolean;
+}
+export interface ThemeRuntime {
+    theme: (...keys: string[]) => string;
+    common: (...keys: string[]) => string;
+    setTheme: (name: string) => void;
+    getTheme: () => string;
+}

package/dist/runtime/virtual-entry.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 用户侧 `@scope/theme-css` 的真实入口。
+ * 配置由 virtual:theme-css/runtime-data 注入，此处是普通 TS。
+ */
+declare const theme: (...keys: string[]) => string, common: (...keys: string[]) => string, setTheme: (name: string) => void, getTheme: () => string;
+export { theme, common, setTheme, getTheme };

package/dist/runtime-entry.cjs

@@ -0,0 +1,76 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/runtime/virtual-entry.ts
+var virtual_entry_exports = {};
+__export(virtual_entry_exports, {
+  common: () => common,
+  getTheme: () => getTheme,
+  setTheme: () => setTheme,
+  theme: () => theme
+});
+module.exports = __toCommonJS(virtual_entry_exports);
+
+// src/runtime/index.ts
+function getByPath(obj, keys) {
+  return keys.reduce((acc, key) => {
+    if (acc && typeof acc === "object" && key in acc) {
+      return acc[key];
+    }
+    return void 0;
+  }, obj);
+}
+function createThemeRuntime(config2, options2 = {}) {
+  const syncHtmlDark = options2.syncHtmlDark ?? true;
+  let currentTheme = typeof document !== "undefined" && document.documentElement.dataset.theme || "light";
+  return {
+    theme(...keys) {
+      const themeTokens = config2.themes?.[currentTheme] ?? {};
+      const value = getByPath(themeTokens, keys);
+      return value !== void 0 ? String(value) : "";
+    },
+    common(...keys) {
+      const value = getByPath(config2.common ?? {}, keys);
+      return value !== void 0 ? String(value) : "";
+    },
+    setTheme(name) {
+      currentTheme = name;
+      if (typeof document !== "undefined") {
+        document.documentElement.dataset.theme = name;
+        if (syncHtmlDark) {
+          document.documentElement.classList.toggle("dark", name === "dark");
+        }
+      }
+    },
+    getTheme() {
+      return currentTheme;
+    }
+  };
+}
+
+// src/runtime/virtual-entry.ts
+var import_runtime_data = require("virtual:theme-css/runtime-data");
+var { theme, common, setTheme, getTheme } = createThemeRuntime(import_runtime_data.config, import_runtime_data.options);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  common,
+  getTheme,
+  setTheme,
+  theme
+});

package/dist/runtime-entry.mjs

@@ -0,0 +1,46 @@
+// src/runtime/index.ts
+function getByPath(obj, keys) {
+  return keys.reduce((acc, key) => {
+    if (acc && typeof acc === "object" && key in acc) {
+      return acc[key];
+    }
+    return void 0;
+  }, obj);
+}
+function createThemeRuntime(config2, options2 = {}) {
+  const syncHtmlDark = options2.syncHtmlDark ?? true;
+  let currentTheme = typeof document !== "undefined" && document.documentElement.dataset.theme || "light";
+  return {
+    theme(...keys) {
+      const themeTokens = config2.themes?.[currentTheme] ?? {};
+      const value = getByPath(themeTokens, keys);
+      return value !== void 0 ? String(value) : "";
+    },
+    common(...keys) {
+      const value = getByPath(config2.common ?? {}, keys);
+      return value !== void 0 ? String(value) : "";
+    },
+    setTheme(name) {
+      currentTheme = name;
+      if (typeof document !== "undefined") {
+        document.documentElement.dataset.theme = name;
+        if (syncHtmlDark) {
+          document.documentElement.classList.toggle("dark", name === "dark");
+        }
+      }
+    },
+    getTheme() {
+      return currentTheme;
+    }
+  };
+}
+
+// src/runtime/virtual-entry.ts
+import { config, options } from "virtual:theme-css/runtime-data";
+var { theme, common, setTheme, getTheme } = createThemeRuntime(config, options);
+export {
+  common,
+  getTheme,
+  setTheme,
+  theme
+};

package/dist/runtime.cjs

@@ -0,0 +1,64 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/runtime/index.ts
+var runtime_exports = {};
+__export(runtime_exports, {
+  createThemeRuntime: () => createThemeRuntime
+});
+module.exports = __toCommonJS(runtime_exports);
+function getByPath(obj, keys) {
+  return keys.reduce((acc, key) => {
+    if (acc && typeof acc === "object" && key in acc) {
+      return acc[key];
+    }
+    return void 0;
+  }, obj);
+}
+function createThemeRuntime(config, options = {}) {
+  const syncHtmlDark = options.syncHtmlDark ?? true;
+  let currentTheme = typeof document !== "undefined" && document.documentElement.dataset.theme || "light";
+  return {
+    theme(...keys) {
+      const themeTokens = config.themes?.[currentTheme] ?? {};
+      const value = getByPath(themeTokens, keys);
+      return value !== void 0 ? String(value) : "";
+    },
+    common(...keys) {
+      const value = getByPath(config.common ?? {}, keys);
+      return value !== void 0 ? String(value) : "";
+    },
+    setTheme(name) {
+      currentTheme = name;
+      if (typeof document !== "undefined") {
+        document.documentElement.dataset.theme = name;
+        if (syncHtmlDark) {
+          document.documentElement.classList.toggle("dark", name === "dark");
+        }
+      }
+    },
+    getTheme() {
+      return currentTheme;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createThemeRuntime
+});

package/dist/runtime.mjs

@@ -0,0 +1,39 @@
+// src/runtime/index.ts
+function getByPath(obj, keys) {
+  return keys.reduce((acc, key) => {
+    if (acc && typeof acc === "object" && key in acc) {
+      return acc[key];
+    }
+    return void 0;
+  }, obj);
+}
+function createThemeRuntime(config, options = {}) {
+  const syncHtmlDark = options.syncHtmlDark ?? true;
+  let currentTheme = typeof document !== "undefined" && document.documentElement.dataset.theme || "light";
+  return {
+    theme(...keys) {
+      const themeTokens = config.themes?.[currentTheme] ?? {};
+      const value = getByPath(themeTokens, keys);
+      return value !== void 0 ? String(value) : "";
+    },
+    common(...keys) {
+      const value = getByPath(config.common ?? {}, keys);
+      return value !== void 0 ? String(value) : "";
+    },
+    setTheme(name) {
+      currentTheme = name;
+      if (typeof document !== "undefined") {
+        document.documentElement.dataset.theme = name;
+        if (syncHtmlDark) {
+          document.documentElement.classList.toggle("dark", name === "dark");
+        }
+      }
+    },
+    getTheme() {
+      return currentTheme;
+    }
+  };
+}
+export {
+  createThemeRuntime
+};

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+export interface ThemeConfig {
+    themes: Record<string, Record<string, any>>;
+    common?: Record<string, any>;
+}
+export interface ThemeCssOptions {
+    /** 配置文件路径，默认 './theme.config.ts' */
+    config?: string;
+    /** SCSS 命名空间，默认 'token' */
+    scssNamespace?: string;
+    /** 是否同步 html.dark，默认 true */
+    syncHtmlDark?: boolean;
+    /** 排除注入 SCSS helper 的文件规则 */
+    exclude?: (string | RegExp)[] | ((filename: string) => boolean);
+}
+export declare const defaultOptions: Required<ThemeCssOptions>;

package/dist/utils/flatten.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 将嵌套对象扁平化为 { 'key1-key2': value } 形式
+ * @param obj 原始嵌套对象
+ * @param prefix 当前前缀
+ */
+export declare const flattenTokens: (obj: Record<string, any>, prefix?: string) => Record<string, string>;

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "vite-plugin-theme-css",
+  "version": "0.1.0",
+  "description": "Vite 插件：用一份主题配置生成 CSS 变量、SCSS helper 与 JS 运行时，支持多主题切换与热更新",
+  "author": "yuzinan <1589937631@qq.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yvygyyth/theme-css.git"
+  },
+  "homepage": "https://github.com/yvygyyth/theme-css#readme",
+  "bugs": {
+    "url": "https://github.com/yvygyyth/theme-css/issues"
+  },
+  "keywords": [
+    "vite",
+    "vite-plugin",
+    "theme",
+    "css",
+    "css-variables",
+    "scss",
+    "dark-mode",
+    "theme-switcher"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.mjs",
+      "require": "./dist/runtime.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "jiti": "^2.7.0"
+  },
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "prettier": "3.9.6",
+    "sass": "^1.103.0",
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.2",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "release": "pnpm publish --access public"
+  }
+}