@ cssxio/ unplugin (英语)

CSSX在这些切入点建立了工具适配器:

import cssxEsbuild from '@cssxio/unplugin/esbuild';
import cssxRollup from '@cssxio/unplugin/rollup';
import cssxRspack from '@cssxio/unplugin/rspack';
import cssxVite from '@cssxio/unplugin/vite';
import cssxWebpack from '@cssxio/unplugin/webpack';

对于Next.js,使用支持的集成. 它准备一个完整的样式表,协调编译器工人,处理App路由器的包含和开发更新,并通过Next的普通样式表管道发送CSS. 浏览器桥会检查页面中已经包含的样式表身份,即使在已变形的JavaScript被 stale时也避免了冗余的初始替换;后来的CSS-只编辑在原子上被应用而无需等待JavaScript HMR.

一体化要求 app/layout.js, (中文(简体) ), app/layout.jsx, (中文(简体) ), app/layout.ts, (中文(简体) ), app/layout.tsx,或者在 src/app。它报告一个没有 App 路由器根布局的项目的配置错误.

// next.config.mjs
import { withCSSX } from '@cssxio/unplugin/next';

export default withCSSX(
  {},
  {
    theme: '@theme reference { --color-brand: #171717; }',
    debug: true,
  },
);

CSSX 默认序列 s…x 姓名和持续姓名 .cssx/classnames.json 生产 withCSSX 建设。 开发使用基于模块身份和CSSX调用顺序的源地址复合名称,因此更改文字或长度会让现有的选择器保持稳定. 开发跳过类名压缩,表写,再用分解计划以及缓存项目元数据,所以一个已存在的源文件只有在变化时才会被再转换. Next.js 16个项目可以选择捆绑器 next dev --webpack 编号 : next build --webpack,或 next dev --turbopack 编号 : next build --turbopack。MDX源文件由帮助者汇编;安装 @mdx-js/mdx 当项目包含时 .md 或者说 .mdx 文档。 配置可序列化的语句、 复韵或矩形插件 mdx启用 sourceRoots 用于项目根外链接的工作空间包.

withCSSX next.js 开发与生产模式。 其他适配器推断开发来自 NODE_ENV=development,活动Vite服务器,开发编译器模式,或Rollup手表模式. Esbuilt 没有标准模式信号, 所以设置 mode: 'development' 当然. mode: 'production' 禁用开发行为.

withCSSX 由同步编曲 webpack(config) 调用。 如果一个已有的回调返回一个承诺, 它会发出一个明显的错误, 因为 Next.js 会同步引用这个钩子 .

命名和编译协调

遗产 stableClassNames: true 选项选择源地址的复合名称(d…)并覆盖预期序列复合输出。 这种行为对于相容性没有变化. 新配置可以选择 naming: 'serial' | 'hash' | 'source' 与 coordination: 'memory' | 'manifest'。 。 。 . className 控制序列或散列原子名称和前缀; naming: 'source' 选择源地址复合材料,而原子名称继续使用 className。 。 。 .

明显的协调将身份分配和序列计数器储存在锁下,然后在解剖上取代JSON文件. 将列表保存在建构之间,以保留系列任务。 新的列表可以指定不同的序列值. 习惯 classNameAllocator 仅是程序内,不能与明显的协调相结合,或 withCSSX。 。 。 .

对于Webpack和Rspack, className 配置 CSSX 内置的分集器,当汇编器实例有相同的项目根和插件选项时,它们共享. 习惯 classNameAllocator 替换内置分配器,且必须不使用 className;它只控制当前进程内的分配。 当编译程序必须共享序列任务时,使用显示协调.

debug: true 打印有效的命名模式、选择器覆盖和编译器绘图状态. debug: { reportFile: 'path/to/report.json' } 撰写JSON报告,内容包括公用事业、源址、生成的班级、选择者检查、明显的协调状况以及相互冲突的公用事业制图. serverClientMappings.status 实值 manifest-shared 当一个清单被配置和收集模块时, mismatch 当一个工具映射到不同的类,或 consistent-in-process 当收集的模块在一个进程分配器下达成一致时.

将选中的通用适配器添加到您的构建工具 plugins 设置 :

// vite.config.ts
import cssx from '@cssxio/unplugin/vite';

export default { plugins: [cssx()] };

带有 Vite 的 Vue 3

在 Vite 插件列表中将 CSSX 置于 Vue 之前 。 CSSX 变换 create 财务报告和审定财务报表 sx 电话 <script>, (中文(简体) ), <script setup>,以及 :class="sx(...)" 模板 装订。 静态平原 class="..." 属性被故意留下.

import cssx from '@cssxio/unplugin/vite';
import vue from '@vitejs/plugin-vue';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [cssx(), vue()] });

// rollup.config.js
import cssx from '@cssxio/unplugin/rollup';

export default { plugins: [cssx({ cssFileName: 'assets/cssx.css' })] };

// webpack.config.js
import cssx from '@cssxio/unplugin/webpack';

export default { plugins: [cssx()] };

// rspack.config.js
import cssx from '@cssxio/unplugin/rspack';

export default { plugins: [cssx()] };

// build.mjs
import cssx from '@cssxio/unplugin/esbuild';
import { build } from 'esbuild';

await build({ entryPoints: ['src/main.ts'], bundle: true, plugins: [cssx()] });

程序化 API

主要入口出口低层 unpluginFactory, 普遍性 unplugin 适配器的例子, 并命名可调用工厂 Vite, Rollup, webpack, Rspack, 和建设。 大多数应用程序应导入上述一个平台入口.

import { transformCssxModule, compileCssxStylesheet } from '@cssxio/unplugin';

const transformed = await transformCssxModule(source, 'src/button.tsx');
const stylesheet = await compileCssxStylesheet([
  {
    id: 'src/button.tsx',
    candidates: transformed?.candidates ?? {},
    origins: transformed?.origins,
    composites: transformed?.composites,
    atomicClasses: transformed?.atomicClasses,
  },
]);

transformCssxModule 返回时 null 除非源模块导入已配置的 CSSX 运行时间 。 否则它返回已转换的JavaScript,候选元数据,复合到原子选择器元数据,源位置,以及当变换创建一个时的JavaScript源图. 通过一个较早相容的版本3源地图作为它的第四个参数来延续该地图.

compileCssxStylesheet 将模块元数据与稳定模块和公用顺序相结合,去掉重复的公用功能,将每个取胜的原子规则别名给使用它的复合类,并返回生成的CSS. 当收集的元数据包括源位置时,它也会返回 CSS 源地图. CssxPluginOptions, (中文(简体) ), TransformResult, (中文(简体) ), IncomingSourceMap, (中文(简体) ), CssxSourceModule,样式表源图类型则从主入口导出.

选项

通用适配器在创建时验证选项. theme 财务报告和审定财务报表 themeFile 无法一起使用 。 无效的 CSS 路径和图层名称在 CSS 发布前失败构建 .

CSSX 默认释放 Tailwind 兼容浏览器基线, 所以实用性 移徙保留了框大小、继承的打字法、联系处理和本地 形式控制正常化。 设定 preflight: false 仅在已有应用程序时 样式表有意拥有不同的全局元素样式.

提取的 CSS

每个生产适配器从最终构建所使用的源文件收集CSS. 当没有被使用的文件有 CSSX 工具时, 它不会创建 CSS 文件 。 默认文件是 cssx.css设置 cssFileName 用另一个相对路径。 CSSX为每个静态样式组成在加分中发出一个复合类,同时在样式表中共享复合选择器之间的声明.

为了遗产 stableClassNames: true cSSX在发布其公共样式表前扫描项目源树。 Next.js集成拥有源编译通道,不要求消费者添加扫描仪,资产重装,样式表链接,或插件钩.

与 Rollup相容的适配器保留已转换的模块元数据,直到 generateBundle,然后将CSS及其地图作为建设资产。 网页软件包和Rspack适配器保留了本地模块的元数据,并在添加阶段释放资产 processAssets。直接 esbuilt 适配器可启用元文件,删除其缺失的源文件的数据,并在其中生成 CSS onEnd。 。 。 .

何时 sourceMap 已启用,有源地址,生成 CSS 有单独的 .css.map 文件和源图注释。 每个映射都指向创建规则的静态公用字符串的源模块位置. transformCssxModule 可以接受并返回JavaScript源图,用于提供相容输入图的构建工具.

在开发过程中,所有适配器都使用缓存的源协调器,并独立于JavaScript捆绑完成而将样式表修改推给只开发的事件流. Vite 服务于它所配置的基础路径下的活动流; Next.js, Webpack, Rspack, Rollup watch, 并明确允许 Esbuild 开发 构建使用回路传输 。 被注入的浏览器桥会自动替换样式表,保留页面状态并避免手动刷新. 在初始文档中保留生成的样式表, 因此 CSS 在第一次更新前就已存在 。 开发监视器和浏览器运输在生产建设中被省略.

CSS源图在开发过程中默认关闭,以减少样式表编译时间和内存使用. 设定 sourceMap: true 当您需要调试生成 CSS 映射时; 制作会保留默认的源地图行为 .

资源使用是在开发期间确定的。 共享项目扫描器在一个过程中最多打开了64个正在运行的所有CSSX项目的目录监视器. Vite and esbuild使用一个本地快道,封顶在另外8个目录监视器上;它们监视目录而不是单个文件,如果本地监视器失败或达到封顶,则会倒回捆绑器监视器. 虚拟组合重复通知和样式表编译,最多同时转换四个已更改的模块,并封顶256个飞行路径。 滚动编制现有仅更新 CSS watchChange 在通过一个队列将重建和序列化的时间排出之前,最多256个待修改模块。 扫描机封顶在256个待取路径上,将相接的相接部分排入一个对齐,并依次更改模块。 被停止的协调员释放其元数据缓存;最多保留了8个不活动的项目快照. 固定大小的文摘避免为编辑检查保留完整的源文本. Vite最多保存了64个已准备好的文摘; 卷起并建造每个封顶,准备64个条目的变换; 估计留存的变换数据的16个MIB. Next.js样式表流每个应用程序最多接受64个浏览器客户端,并且只保留一个慢客户端的最新更新队列.

如果一个Vite-power-SSR框架跳过Vite的HTML变换钩子,CSSX会在被制成的响应中注入它的桥. 倒置缓冲器每次响应最多为1个米B和4,096个块,最多一次有8个响应缓冲;过量或过量响应不注射而通过.

100 ms 的入球测量一个温和的现有风格的保存,直到下一个动画框之后的已改变的计算样式可见为止. 它不包括冷启动,新引入的调用站点,JavaScript编辑,全主题变化,或组成-结构变化. 运行 pnpm benchmark:dev-hmr 用于缓存编译器基准和 pnpm test:hmr 用于浏览器保存到可见的基准 横跨 Esbuild, Rollup, Webpack, 和 Rspack. Vite和Next.js浏览器的基准运行在视觉测试矩阵中. 单是编译器计时就不是一个浏览器保存到可见的测量.

随着重建, outdir 将 CSS 置于目录下方. outfile 将其放在输出文件旁边。 没有两种选择,它都放在工作目录下。 与 write: false, CSS 及其地图附在 Esbuilt 的记忆中 outputFiles;否则它们会被写入磁盘. 后期的 Esbuild 架构删除 CSSX 在没有公用设施存在时所写的 CSS 文件 .

见 工作空间读取 用于CSSX语法、支持的公用事业和当前排除.