esbuild-less-inject

一个轻量高效的 esbuild 插件，用于将 Less/CSS 文件编译并注入到 JavaScript 运行时中，支持 CSS Modules 规范。

特性

• 🚀 零运行时依赖 - 仅依赖 less 编译器
• 📦 自动注入 - 编译后的 CSS 自动插入到 document.head
• 🎯 CSS Modules - 原生支持 .module.less 作用域隔离
• 🔒 防重复注入 - 基于内容哈希的智能去重
• 💪 TypeScript 友好 - 自动生成命名导出类型
• ⚡ 高性能 - 利用 esbuild 的并行处理能力

安装

bash npm install esbuild-less-inject less --save-dev

使用示例

基础配置

javascript // esbuild.config.js import { build } from 'esbuild'; import { esbuildLessInject } from 'esbuild-less-inject';

build({ entryPoints: ['src/index.js'], bundle: true, plugins: [esbuildLessInject()], }).catch(() => process.exit(1));

普通 Less 文件

less / styles.less / .header { color: red; }

javascript import './styles.less'; // 自动注入样式

CSS Modules 用法

less / styles.module.less / .container { padding: 20px; }

.title { font-size: 16px; }

javascript import styles from './styles.module.less';

// 使用哈希类名 document.body.innerHTML = `

// 同时支持 camelCase 导出 import { container, title } from './styles.module.less';

API

esbuildLessInject()

当前版本无需配置选项，所有行为基于文件约定：

| 文件模式 | 行为 | |---------|------| | *.less | 全局样式，注入到 head | | *.module.less | CSS Modules，生成作用域类名 |

实现原理

1. Less 编译：使用 less.render() 编译源文件
2. 作用域处理：对 .module.less 文件遍历 AST，为类名添加 hy-{hash} 前缀
3. 运行时注入：生成 IIFE 检查环境变量，避免 SSR 报错
4. 导出策略：
   • 普通 Less：导出原始 CSS 字符串
   • CSS Modules：导出 { originalName: scopedName } 映射对象

注意事项

• 插件仅处理 .less 文件，CSS 文件需先重命名为 .less
• 浏览器环境依赖 document 对象，SSR 场景自动跳过
• 全局变量 __HUXY__ 用于追踪已注入样式，请勿覆盖
• 类名转换规则：.header-title → hy{a1b2c3}-header-title

License

MIT