vite-plugin-theme-css 0.1.0 → 0.2.0

package/README.md

@@ -76,14 +76,16 @@ export default defineConfig({
 })
 ```
 
-### 3. 引入 CSS 变量
+### 3. CSS 变量（自动注入）
 
-在入口文件中导入虚拟 CSS：
+默认会在 HTML 里自动注入主题 CSS 变量，**无需**在入口手动写：
 
 ```ts
-import 'virtual:theme-css/css'
+import 'virtual:theme-css/css' // 可省略
 ```
 
+若需关闭自动注入，可设置 `autoImportCss: false`，再自行在入口 import。
+
 生成示例：
 
 ```css
@@ -173,8 +175,11 @@ themeCss({
   syncHtmlDark: true,
 
   /** 排除自动注入 SCSS helper 的文件 */
-  exclude: [/node_modules/]
+  exclude: [/node_modules/],
   // 或: (filename) => filename.includes('legacy')
+
+  /** 是否自动在 HTML 注入 CSS 变量，默认 true */
+  autoImportCss: true
 })
 ```
 

package/dist/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const VIRTUAL_CSS_ID = "virtual:theme-css/css";
+export declare const VIRTUAL_CSS_RESOLVED = "\0virtual:theme-css.css";
+export declare const VIRTUAL_SCSS_ID = "virtual:theme-css/scss";
+export declare const VIRTUAL_SCSS_RESOLVED = "\0virtual:theme-css.scss";
+export declare const VIRTUAL_RUNTIME_ID = "@scope/theme-css";
+export declare const VIRTUAL_RUNTIME_DATA_ID = "virtual:theme-css/runtime-data";
+export declare const VIRTUAL_RUNTIME_DATA_RESOLVED = "\0virtual:theme-css/runtime-data";

package/dist/index.cjs

@@ -41,12 +41,22 @@ var import_node_url = require("url");
 var import_node_module = require("module");
 var import_jiti = require("jiti");
 
+// src/constants.ts
+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";
+
 // src/types.ts
 var defaultOptions = {
   config: "./theme.config.ts",
   scssNamespace: "token",
   syncHtmlDark: true,
-  exclude: []
+  exclude: [],
+  autoImportCss: true
 };
 
 // src/utils/flatten.ts
@@ -86,8 +96,8 @@ var generateThemeCss = (config) => {
   return lines.join("\n");
 };
 
-// src/generate/scss/helper.scss
-var helper_default = `// \u5185\u90E8\u5DE5\u5177\uFF1A\u62FC\u63A5\u591A\u4E2A key\r
+// src/generate/scss/index.ts
+var generateScssHelper = () => `// \u5185\u90E8\u5DE5\u5177\uFF1A\u62FC\u63A5\u591A\u4E2A key\r
 @function _join-keys($keys...) {\r
   $result: '';\r
   @each $key in $keys {\r
@@ -118,9 +128,6 @@ var helper_default = `// \u5185\u90E8\u5DE5\u5177\uFF1A\u62FC\u63A5\u591A\u4E2A
 }\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)}
@@ -128,6 +135,23 @@ export const options = ${JSON.stringify(options)}
 `;
 }
 
+// src/utils/sass-importer.ts
+var canonicalUrl = new URL(`${VIRTUAL_SCSS_ID}.scss`);
+function createVirtualScssImporter(getContent) {
+  return {
+    canonicalize(url) {
+      if (url === VIRTUAL_SCSS_ID) return canonicalUrl;
+      return null;
+    },
+    load(canonical) {
+      if (canonical.href === canonicalUrl.href) {
+        return { contents: getContent(), syntax: "scss" };
+      }
+      return null;
+    }
+  };
+}
+
 // src/defineTheme.ts
 function defineTheme(config) {
   return config;
@@ -174,13 +198,6 @@ function createThemeRuntime(config, options = {}) {
 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");
@@ -189,11 +206,8 @@ function resolveRuntimeEntryPath() {
 }
 function themeCss(options = {}) {
   const resolvedOptions = { ...defaultOptions, ...options };
-  const { config: configPath, scssNamespace, syncHtmlDark, exclude } = resolvedOptions;
-  let viteConfig;
-  let themeConfig;
+  const { config: configPath, scssNamespace, syncHtmlDark, exclude, autoImportCss } = resolvedOptions;
   let cssContent = "";
-  let scssHelperContent = "";
   let runtimeDataContent = "";
   const runtimeEntryPath = resolveRuntimeEntryPath();
   async function loadConfigAndGenerate() {
@@ -211,15 +225,13 @@ ${source}`;
       }
     });
     const mod = await jiti.import(import_node_path.default.resolve(configPath));
-    themeConfig = mod.default;
+    const themeConfig = mod.default;
     cssContent = generateThemeCss(themeConfig);
-    scssHelperContent = generateScssHelper();
     runtimeDataContent = generateJs(themeConfig, { syncHtmlDark });
   }
   return {
     name: "vite-plugin-theme-css",
-    async configResolved(config) {
-      viteConfig = config;
+    async configResolved() {
       await loadConfigAndGenerate();
     },
     resolveId(id) {
@@ -241,7 +253,7 @@ ${source}`;
         case VIRTUAL_CSS_RESOLVED:
           return cssContent;
         case VIRTUAL_SCSS_RESOLVED:
-          return scssHelperContent;
+          return generateScssHelper();
         case VIRTUAL_RUNTIME_DATA_RESOLVED:
           return runtimeDataContent;
         default:
@@ -253,32 +265,53 @@ ${source}`;
       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 applyUserAdditionalData = async (source, filename) => {
+        if (typeof userAdditionalData === "function") {
+          return userAdditionalData(source, filename);
         }
-        const shouldExclude = Array.isArray(exclude) ? exclude.some((rule) => {
+        if (userAdditionalData) {
+          return userAdditionalData + source;
+        }
+        return source;
+      };
+      const wrappedAdditionalData = async (source, filename) => {
+        const skipInject = filename.includes("virtual:theme-css") || (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 ?? "";
+        }) : typeof exclude === "function" ? exclude(filename) : false);
+        if (skipInject) {
+          return applyUserAdditionalData(source, filename);
         }
-        const userContent = typeof userAdditionalData === "function" ? await userAdditionalData(source, filename) : userAdditionalData ?? "";
-        return ourPrefix + userContent;
+        return ourPrefix + await applyUserAdditionalData(source, filename);
       };
+      const userImporters = Array.isArray(scssOptions.importers) ? scssOptions.importers : [];
       return {
         css: {
           preprocessorOptions: {
             scss: {
               ...scssOptions,
-              additionalData: wrappedAdditionalData
+              additionalData: wrappedAdditionalData,
+              importers: [
+                createVirtualScssImporter(generateScssHelper),
+                ...userImporters
+              ]
             }
           }
         }
       };
     },
+    transformIndexHtml(html) {
+      if (!autoImportCss || html.includes(VIRTUAL_CSS_ID)) return;
+      return [
+        {
+          tag: "script",
+          attrs: { type: "module" },
+          children: `import ${JSON.stringify(VIRTUAL_CSS_ID)};`,
+          injectTo: "head-prepend"
+        }
+      ];
+    },
     async handleHotUpdate(ctx) {
       const configAbsPath = import_node_path.default.resolve(configPath);
       if (ctx.file === configAbsPath) {
@@ -286,7 +319,6 @@ ${source}`;
         const moduleGraph = ctx.server.moduleGraph;
         for (const id of [
           VIRTUAL_CSS_RESOLVED,
-          VIRTUAL_SCSS_RESOLVED,
           VIRTUAL_RUNTIME_DATA_RESOLVED,
           runtimeEntryPath
         ]) {

package/dist/index.mjs

@@ -5,12 +5,22 @@ import { fileURLToPath } from "url";
 import { createRequire } from "module";
 import { createJiti } from "jiti";
 
+// src/constants.ts
+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";
+
 // src/types.ts
 var defaultOptions = {
   config: "./theme.config.ts",
   scssNamespace: "token",
   syncHtmlDark: true,
-  exclude: []
+  exclude: [],
+  autoImportCss: true
 };
 
 // src/utils/flatten.ts
@@ -50,8 +60,8 @@ var generateThemeCss = (config) => {
   return lines.join("\n");
 };
 
-// src/generate/scss/helper.scss
-var helper_default = `// \u5185\u90E8\u5DE5\u5177\uFF1A\u62FC\u63A5\u591A\u4E2A key\r
+// src/generate/scss/index.ts
+var generateScssHelper = () => `// \u5185\u90E8\u5DE5\u5177\uFF1A\u62FC\u63A5\u591A\u4E2A key\r
 @function _join-keys($keys...) {\r
   $result: '';\r
   @each $key in $keys {\r
@@ -82,9 +92,6 @@ var helper_default = `// \u5185\u90E8\u5DE5\u5177\uFF1A\u62FC\u63A5\u591A\u4E2A
 }\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)}
@@ -92,6 +99,23 @@ export const options = ${JSON.stringify(options)}
 `;
 }
 
+// src/utils/sass-importer.ts
+var canonicalUrl = new URL(`${VIRTUAL_SCSS_ID}.scss`);
+function createVirtualScssImporter(getContent) {
+  return {
+    canonicalize(url) {
+      if (url === VIRTUAL_SCSS_ID) return canonicalUrl;
+      return null;
+    },
+    load(canonical) {
+      if (canonical.href === canonicalUrl.href) {
+        return { contents: getContent(), syntax: "scss" };
+      }
+      return null;
+    }
+  };
+}
+
 // src/defineTheme.ts
 function defineTheme(config) {
   return config;
@@ -137,13 +161,6 @@ function createThemeRuntime(config, options = {}) {
 // 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");
@@ -152,11 +169,8 @@ function resolveRuntimeEntryPath() {
 }
 function themeCss(options = {}) {
   const resolvedOptions = { ...defaultOptions, ...options };
-  const { config: configPath, scssNamespace, syncHtmlDark, exclude } = resolvedOptions;
-  let viteConfig;
-  let themeConfig;
+  const { config: configPath, scssNamespace, syncHtmlDark, exclude, autoImportCss } = resolvedOptions;
   let cssContent = "";
-  let scssHelperContent = "";
   let runtimeDataContent = "";
   const runtimeEntryPath = resolveRuntimeEntryPath();
   async function loadConfigAndGenerate() {
@@ -174,15 +188,13 @@ ${source}`;
       }
     });
     const mod = await jiti.import(path.resolve(configPath));
-    themeConfig = mod.default;
+    const themeConfig = mod.default;
     cssContent = generateThemeCss(themeConfig);
-    scssHelperContent = generateScssHelper();
     runtimeDataContent = generateJs(themeConfig, { syncHtmlDark });
   }
   return {
     name: "vite-plugin-theme-css",
-    async configResolved(config) {
-      viteConfig = config;
+    async configResolved() {
       await loadConfigAndGenerate();
     },
     resolveId(id) {
@@ -204,7 +216,7 @@ ${source}`;
         case VIRTUAL_CSS_RESOLVED:
           return cssContent;
         case VIRTUAL_SCSS_RESOLVED:
-          return scssHelperContent;
+          return generateScssHelper();
         case VIRTUAL_RUNTIME_DATA_RESOLVED:
           return runtimeDataContent;
         default:
@@ -216,32 +228,53 @@ ${source}`;
       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 applyUserAdditionalData = async (source, filename) => {
+        if (typeof userAdditionalData === "function") {
+          return userAdditionalData(source, filename);
         }
-        const shouldExclude = Array.isArray(exclude) ? exclude.some((rule) => {
+        if (userAdditionalData) {
+          return userAdditionalData + source;
+        }
+        return source;
+      };
+      const wrappedAdditionalData = async (source, filename) => {
+        const skipInject = filename.includes("virtual:theme-css") || (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 ?? "";
+        }) : typeof exclude === "function" ? exclude(filename) : false);
+        if (skipInject) {
+          return applyUserAdditionalData(source, filename);
         }
-        const userContent = typeof userAdditionalData === "function" ? await userAdditionalData(source, filename) : userAdditionalData ?? "";
-        return ourPrefix + userContent;
+        return ourPrefix + await applyUserAdditionalData(source, filename);
       };
+      const userImporters = Array.isArray(scssOptions.importers) ? scssOptions.importers : [];
       return {
         css: {
           preprocessorOptions: {
             scss: {
               ...scssOptions,
-              additionalData: wrappedAdditionalData
+              additionalData: wrappedAdditionalData,
+              importers: [
+                createVirtualScssImporter(generateScssHelper),
+                ...userImporters
+              ]
             }
           }
         }
       };
     },
+    transformIndexHtml(html) {
+      if (!autoImportCss || html.includes(VIRTUAL_CSS_ID)) return;
+      return [
+        {
+          tag: "script",
+          attrs: { type: "module" },
+          children: `import ${JSON.stringify(VIRTUAL_CSS_ID)};`,
+          injectTo: "head-prepend"
+        }
+      ];
+    },
     async handleHotUpdate(ctx) {
       const configAbsPath = path.resolve(configPath);
       if (ctx.file === configAbsPath) {
@@ -249,7 +282,6 @@ ${source}`;
         const moduleGraph = ctx.server.moduleGraph;
         for (const id of [
           VIRTUAL_CSS_RESOLVED,
-          VIRTUAL_SCSS_RESOLVED,
           VIRTUAL_RUNTIME_DATA_RESOLVED,
           runtimeEntryPath
         ]) {

package/dist/types.d.ts

@@ -11,5 +11,7 @@ export interface ThemeCssOptions {
     syncHtmlDark?: boolean;
     /** 排除注入 SCSS helper 的文件规则 */
     exclude?: (string | RegExp)[] | ((filename: string) => boolean);
+    /** 是否自动在 HTML 注入 CSS 变量，默认 true */
+    autoImportCss?: boolean;
 }
 export declare const defaultOptions: Required<ThemeCssOptions>;

package/dist/utils/sass-importer.d.ts

@@ -0,0 +1,3 @@
+import type { Importer } from 'sass';
+/** 让 Sass 能解析 additionalData 里的 virtual:theme-css/scss */
+export declare function createVirtualScssImporter(getContent: () => string): Importer<'sync'>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-theme-css",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Vite 插件：用一份主题配置生成 CSS 变量、SCSS helper 与 JS 运行时，支持多主题切换与热更新",
   "author": "yuzinan <1589937631@qq.com>",
   "license": "MIT",
@@ -53,6 +53,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
+    "esbuild": "^0.28.2",
     "prettier": "3.9.6",
     "sass": "^1.103.0",
     "tsup": "^8.5.1",
@@ -63,6 +64,7 @@
   "scripts": {
     "build": "tsup && tsc -p tsconfig.build.json",
     "dev": "tsup --watch",
+    "play": "vite --config playground/vite.config.ts",
     "test": "vitest",
     "format": "prettier --write .",
     "format:check": "prettier --check .",