npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

vite-plugin-theme-css

v0.5.1

Published

Vite 插件:theme.config → 编译期 SCSS(CSS 变量 + helper)+ 运行时 globalThis.__THEME_CSS__ 深合并

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        # playground

License

MIT