框架
为应用选择受支持的 StyleX 集成。
Vite 与 Rolldown
新建 React TypeScript 应用时使用官方 Vite 模板;已有应用可跳过以下创建命令:
npm create vite@9.3.4 my-app -- --template react-ts
cd my-app
npm install在应用根目录安装 Lenso 与官方 StyleX 集成:
npm install @lenso/ui @lenso/tokens @stylexjs/stylex@0.19.1
npm install -D @stylexjs/unplugin@0.19.1这套配置已在 Vite 8.3.8、React 19.3.1 和 @vitejs/plugin-react 6.3.0 中验证。Lenso 发布包含 StyleX 声明的普通模块,插件统一编译库与应用的样式。
Vite 配置
用下面的完整配置替换模板的 vite.config.ts,或将 StyleX 插件合并到现有 React 插件之前,保留其他应用配置。rootDir 指定应用根目录,供编译器解析导入的 StyleX 常量。
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { unplugin as stylex } from "@stylexjs/unplugin";
export default defineConfig({
optimizeDeps: {
exclude: ["@lenso/ui", "@lenso/tokens", "@lenso/glass"],
include: ["use-sync-external-store/shim", "use-sync-external-store/shim/with-selector"],
},
plugins: [
stylex.vite({
dev: false,
runtimeInjection: false,
useCSSLayers: false,
lightningcssOptions: { exclude: 4 },
unstable_moduleResolution: {
type: "commonJS",
rootDir: import.meta.dirname,
},
}),
react(),
],
});具名 unplugin 导出兼容模板的 NodeNext 类型配置。optimizeDeps.exclude 保证开发模式中的 Lenso 声明经过 StyleX 编译。optimizeDeps.include 则预构建 UI SDK 使用的 CommonJS 依赖,同时保留 Lenso 声明供样式编译,详见 Vite 依赖优化。
Vite 入口与示例
替换模板的 src/main.tsx 和 src/App.tsx。入口加载主题与基础 CSS,并提供主题作用域;UI SDK 弹出层在原位置渲染到浏览器顶层时会继承它。深色主题使用 theme="dark"。示例移除了模板的 index.css 和 App.css 导入,这些初始样式会限制页面尺寸并覆盖按钮外观;接入已有应用时保留自己需要的全局样式。
// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { ThemeScope } from "@lenso/ui";
import "@lenso/tokens/styles.css";
import App from "./App";
createRoot(document.getElementById("root")!).render(
<StrictMode><ThemeScope theme="light"><App /></ThemeScope></StrictMode>,
);在 stylex.create 中使用 token 时,从 @lenso/tokens/tokens.stylex.const 直接导入。下面的示例同时验证本地 xstyle 覆盖、状态更新和通过原生顶层展开的 Glass 菜单:
// src/App.tsx
import { useState } from "react";
import * as stylex from "@stylexjs/stylex";
import { tokens } from "@lenso/tokens/tokens.stylex.const";
import { Button, GlassButton, Menu } from "@lenso/ui";
const styles = stylex.create({
page: {
minHeight: "100vh",
padding: 32,
backgroundColor: tokens.backgroundGroupedPrimary,
color: tokens.labelPrimary,
},
action: { minWidth: 180 },
});
export default function App() {
const [count, setCount] = useState(0);
return (
<main {...stylex.props(styles.page)}>
<Button variant="prominent" xstyle={styles.action} onClick={() => setCount(count + 1)}>
Count {count}
</Button>
<Menu.Root morphTrigger={false}>
<Menu.Trigger render={<GlassButton />}>Actions</Menu.Trigger>
<Menu.Content><Menu.Item onClick={() => setCount(0)}>Reset count</Menu.Item></Menu.Content>
</Menu.Root>
</main>
);
}验证 Vite
启动开发服务器并打开输出的地址:
npm run dev随后停止开发服务器,构建应用并打开生产预览地址:
npm run build
npm run preview两种模式下,Count 都应为蓝色圆角按钮,宽度至少 180px。点击后数值递增;Actions 打开带样式的菜单,Reset count 将数值归零。也应检查深色主题。构建成功不能单独证明样式已交付:遗漏主题与基础 CSS,或未真正接入 StyleX 插件,都可能让控件失去样式。不需要 Lenso 构建适配器或生成包 metadata。
Rolldown 与 SSR
Rolldown 使用 stylex.rolldown。配置 Lightning CSS 目标时保留原生 :dir()。上面的可运行流程验证的是 Vite 客户端应用,不包含 Rolldown 或 SSR 宿主配置。
Vite SSR 需要编译这些源码包,不能将它们作为外部依赖跳过编译:
ssr: { noExternal: ["@lenso/ui", "@lenso/tokens", "@lenso/glass"] }使用文档框架时还需包含 @lenso/docs。直接通过 Node 导入不会编译 StyleX 声明。仅服务端使用的样式也必须进入应用的 CSS 编译;仅客户端依赖图不能证明它们已被交付。
Next.js App Router
在已有的 TypeScript App Router 项目根目录执行以下命令。这套配置已在 Next.js 16.4.6(默认 Turbopack 构建)、React 19.3.1 和以下包版本中验证,使用官方 StyleX Babel 与 PostCSS 插件。
npm install @lenso/ui @lenso/tokens @stylexjs/stylex@0.19.1
npm install -D @babel/core@7.29.7 @stylexjs/babel-plugin@0.19.1 @stylexjs/postcss-plugin@0.19.1配置编译
将 transpilePackages 合并到现有 Next 配置中。在项目根目录将 Babel 配置保存为 babel.config.json。
// next.config.ts
export default { transpilePackages: ["@lenso/tokens"] };{
"presets": ["next/babel"],
"plugins": [["@stylexjs/babel-plugin", {
"dev": false,
"runtimeInjection": false,
"treeshakeCompensation": true,
"unstable_moduleResolution": { "type": "commonJS" }
}]]
}在同一根目录创建 postcss.config.cjs。已有 PostCSS 配置时合并插件,不要保留两份配置文件。显式的包路径会扫描已安装的各组件样式声明。
// postcss.config.cjs
const babel = require("./babel.config.json");
module.exports = {
plugins: {
"@stylexjs/postcss-plugin": {
include: [
"./src/**/*.{js,jsx,ts,tsx}",
"./app/**/*.{js,jsx,ts,tsx}",
"./components/**/*.{js,jsx,ts,tsx}",
"./node_modules/@lenso/tokens/dist/**/*.js",
],
babelConfig: {
babelrc: false,
configFile: false,
parserOpts: { plugins: ["typescript", "jsx"] },
plugins: babel.plugins,
},
},
},
};这些路径相对于包含 node_modules 的应用根目录;使用其他源码目录或仅服务端 StyleX 声明时,需要扩展 include。不要用 require.resolve("@lenso/tokens/package.json") 生成扫描路径,这个入口未公开导出。改为解析 styles.css 也不适用:Turbopack 可能将结果改写为虚拟 CSS 模块标识,导致构建成功却没有生成组件样式。
加载 CSS 与主题
创建全局样式表并从根布局导入。使用 src/app 的项目将这些文件放在对应目录中,保留现有布局元数据和其他 Provider。
/* app/globals.css */
@import "@lenso/tokens/styles.css";
@stylex;// app/layout.tsx
import "./globals.css";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>{children}</body>
</html>
);
}根布局保持为 Server Component。将 ThemeScope 放在客户端边界内,如下面的页面示例;深色主题使用 theme="dark"。UI SDK 弹出层在原位置渲染到浏览器顶层,并继承所在的 ThemeScope,无需 Portal 部件。每个根布局,以及替代布局的自定义 global-error 或 global-not-found 文档,都必须导入这份样式表。CSS 交付、哈希和清单由 Next 管理。
渲染与验证
下面的客户端页面同时演示应用 xstyle 覆盖、主题 token、状态更新和通过原生顶层展开的 Glass 菜单。在 StyleX 声明中从 @lenso/tokens/tokens.stylex.const 直接导入 token,供编译器解析常量。
// app/page.tsx
"use client";
import { useState } from "react";
import * as stylex from "@stylexjs/stylex";
import { tokens } from "@lenso/tokens/tokens.stylex.const";
import { Button, GlassButton, Menu, ThemeScope } from "@lenso/ui";
const styles = stylex.create({
page: {
minHeight: "100vh",
padding: 32,
backgroundColor: tokens.backgroundGroupedPrimary,
color: tokens.labelPrimary,
},
action: { minWidth: 180 },
});
export default function Page() {
const [count, setCount] = useState(0);
return (
<ThemeScope theme="light">
<main {...stylex.props(styles.page)}>
<Button variant="prominent" xstyle={styles.action} onClick={() => setCount(count + 1)}>
Count {count}
</Button>
<Menu.Root morphTrigger={false}>
<Menu.Trigger render={<GlassButton />}>Actions</Menu.Trigger>
<Menu.Content><Menu.Item onClick={() => setCount(0)}>Reset count</Menu.Item></Menu.Content>
</Menu.Root>
</main>
</ThemeScope>
);
}构建并启动生产应用:
npm run build
npm run startCount 按钮应为蓝色圆角按钮,宽度至少 180px。点击后数值递增;Actions 打开带样式的菜单,Reset count 将数值归零。即使构建成功,没有样式的页面也不能视为接入成功,应检查主题 CSS 导入和 PostCSS 的包扫描路径。修正 StyleX 编译错误后,如果下一次构建仍显示旧源码,先停止 Next,仅删除生成的 .next 目录,再重新构建。