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

unplugin-favicon-identity

v0.2.0

Published

Give every project a stable, readable dev-server favicon so you can tell browser tabs apart at a glance

Readme

unplugin-favicon-identity

English | 简体中文

npm 版本 npm 下载量 单元测试 许可证

打开在线预览站 →

给每个项目一枚属于自己的开发环境 favicon —— 一块圆角色块,写着项目名的首字 —— 这样不看标题也能 分清浏览器标签页。

// vite.config.ts
import { defineConfig } from 'vite'
import faviconIdentity from 'unplugin-favicon-identity/vite'

export default defineConfig({
  plugins: [faviconIdentity()],
})

配置就这些。名字取自 index.html 的 <title>,不需要额外填什么:

| 项目 | title | 图标 | | --- | --- | --- | | A | 复发性流产专科病历 | 复 | | B | 门诊随访系统 | 门 | | C | PACS 影像工作站 | P |

每个项目一个颜色,而且同一个项目永远是同一个颜色 —— 不会每次重启都换一副面孔。

dev 与生产构建都支持。dev 下图标由 dev server 直接从内存返回;生产构建时会把 SVG 输出到产物 根目录的 __favicon-identity.svg,并把 <link rel="icon"> 改写成指向它。如果不想让图标出现 在构建产物里,只在开发时加载插件即可:

// vite.config.ts
export default defineConfig(({ command }) => ({
  plugins: [command === 'serve' && faviconIdentity()],
}))

安装

npm i -D unplugin-favicon-identity

支持 Vite 5 / 6 / 7 / 8 与 webpack 5。

webpack

// webpack.config.ts
import HtmlWebpackPlugin from 'html-webpack-plugin'
import faviconIdentity from 'unplugin-favicon-identity/webpack'

export default {
  plugins: [new HtmlWebpackPlugin({ template: 'index.html' }), faviconIdentity()],
}

插件会把 SVG 作为 asset 输出,并在 PROCESS_ASSETS_STAGE_SUMMARIZE 阶段改写所有 .html asset,所以由其他插件生成的 HTML 也能覆盖到。output.publicPath 是字符串时按它拼 URL,否则 使用相对于页面的路径。

dev server 不需要额外配置:webpack-dev-server 会直接从内存文件系统提供这个 SVG,<link> 指向的地址即可访问。不支持 webpack 4。

选项

| 选项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | text | string | <title> → 目录名 | 取首字的那段文字 | | bgColor | string | 由名字派生 | 任意 CSS 颜色,如 oklch(0.5 0.1 200) | | textColor | 'light' \| 'dark' | 'light' | 文字色预设,同时决定背景的亮度区间 | | render | (data) => string | 内置模板 | 返回完整的 SVG 字符串 | | debug | boolean | false | 在终端打印名字与颜色 |

自定义模板

faviconIdentity({
  render: ({ char, background, foreground }) => `<svg xmlns="http://www.w3.org/2000/svg"
    width="64" height="64" viewBox="0 0 64 64">
    <circle cx="32" cy="32" r="32" fill="${background}"/>
    <text x="32" y="32" fill="${foreground}" font-size="44" text-anchor="middle"
      dominant-baseline="central">${char}</text>
  </svg>`,
})

你会拿到 char、background、foreground,画成什么形状由你决定,但下面的颜色契约依然成立。 如果模板里要拼 char,记得转义 —— 内置模板用的是导出的 escapeXml。

颜色是怎么来的

sha256(名字) 给出两个互相独立的小数:第 0 个 32 位字定色相,第 4 个 32 位字在固定区间里插值出 亮度。彩度则被推到该亮度、该色相下 sRGB 色域的边界。其余的字是预留位,以后加参数不会挪动 这两个已经决定颜色的值。Node 端由库负责对名字做 SHA-256;/web 入口则直接接收摘要,所以任意 运行时都适用同一套规则。

由此得到三条性质,都有测试兜底:

  1. 确定:同一个项目名永远是同一个颜色。哈希只要微秒级,所以没有缓存,也就没有缓存过期的问题。
  2. 永不被色域裁切。这一条比听起来重要:颜色超出 sRGB 时,浏览器不会保持亮度 —— 它会把 linear 分量直接钳到 [0, 1],亮度随之悄悄漂移(实测请求 L=0.53,渲染出来是 0.68)。一旦 发生这种事,亮度区间就不再控制得了对比度。把彩度压在边界内就绕开了整个问题。
  3. 可读。OKLab 的亮度是感知亮度,加上每个文字色预设对应一组写死的区间,对比度在生成时就 确定了,不需要事后校验。穷举 360 个色相后的最差情况:light 预设 5.20:1、dark 预设 4.76:1(WCAG AA 要求 4.5:1)。

彩度不是一个小常数,而这正是生成配色看起来发灰的常见原因。每个色相都取到自己的上限 —— 青色 大约只能到 C=0.09,品红能到 0.29 —— 所以每个颜色都是该亮度下 sRGB 允许的最鲜艳版本。

打开 faviconIdentity({ debug: true }) 就能看到你的项目拿到了什么:

  🎨 [favicon-identity] 门诊随访系统 → oklch(0.511 0.254 311)

程序化 API

Node

import { createFavicon, createIdentityColor } from 'unplugin-favicon-identity'

const { svg, background } = createFavicon('门诊随访系统')
const color = createIdentityColor('门诊随访系统', 'light') // { lightness, chroma, hue }

任意运行时(包括浏览器)

unplugin-favicon-identity/web 不含任何 Node API,且保持同步。调用方只需要提供 SHA-256 摘要, 浏览器里直接用 Web Crypto:

import { createFaviconFromHash } from 'unplugin-favicon-identity/web'

const name = '门诊随访系统'
const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(name))
const { svg, background, version } = createFaviconFromHash({ text: name, hash })

hash 可以是 ArrayBuffer 或 Uint8Array。两个入口共用同一套颜色与 SVG 代码,同一个名字在任一端 生成的图标完全一致。

另外还导出:formatOklch、buildFaviconSvg、escapeXml,以及 OklchColor、TextColor、 FaviconRenderData、Favicon、FaviconOptions 类型(FaviconFromHashOptions 仅 web 入口)。 core 里其余的东西——色域计算、HTML 解析、对比度校验——都是内部实现,可能随版本调整, 不承诺兼容。对比度由测试套件校验,不作为 API 暴露。

注意事项

  • dev 下图标由 /{base}__favicon-identity.svg 提供,带 Cache-Control: no-store;<link> 上 还挂了由名字派生的指纹(?v=…),避免浏览器缓存的旧图标赖着不走。webpack 下同一地址由 dev server 从内存文件系统直接提供。两种构建器的生产产物都会在根目录写出 __favicon-identity.svg。
  • 已有的 <link rel="icon"> 会被替换掉,多余的会被删除;一个都没有就在 </head> 前插一个。
  • 首个字符按字素簇切分,emoji 的组合序列(👨‍👩‍👧、👍🏽)不会被拆散。

开发

bun install
bun test        # 颜色契约、名字解析、SVG 转义
bun run build   # tsup → dist(esm + cjs + dts)
bun run playground        # 本地 React 预览站
bun run build:playground  # 静态站点 → playground/dist

许可证

MIT