跳至内容

快速开始

安装 React、主题与构建包,并正确交付编译后的样式。

先选择框架集成:Vite / Rolldown 或 Next.js App Router,再完成以下安装。

环境要求

使用符合 @lenso/ui 公布的 peer 范围的 React 和 React DOM,以及 @stylexjs/unplugin 支持的打包器。Lenso 不需要 Tailwind。

软件包

React 包名为 @lenso/ui,主题与组件样式映射由 @lenso/tokens 提供。UI 与 tokens 应使用匹配的 Lenso 版本。React 和 React DOM 必须满足 React 包公布的 peer 范围。

npm install @lenso/ui @lenso/tokens @stylexjs/stylex@0.19.1
npm install -D @stylexjs/unplugin@0.19.1
使用未发布候选

未发布候选使用仓库工作区或打包产物。安装前核对构建包支持的编译器和打包器版本;本指南不证明候选已发布。

主题样式表

在实际渲染文档的布局中加载:

// 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>,
);

入口提供 light 主题,深色主题使用 theme="dark"。替换 Vite 模板入口时移除模板的 index.css 与 App.css 导入,保留应用自己的样式。UI SDK 弹出层在原位置渲染到浏览器顶层,无需 Portal 部件即可继承主题作用域。自行创建 Portal 时,需显式保留其主题作用域。仅在兄弟布局加载的样式表不能为此文档提供样式。

可以从一个实际操作开始:

// src/App.tsx
import { Button } from "@lenso/ui";

export default function App() {
  return <Button onClick={() => console.log("Saved")}>保存更改</Button>;
}

依赖生产样式前,完成下方构建集成。

应用 StyleX

使用官方 StyleX 插件统一编译 Lenso 发布的声明和应用样式:

// 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(),
  ],
});

开发模式保留 optimizeDeps.exclude 与 CommonJS 的 optimizeDeps.include 配置;模板的 NodeNext 配置使用具名 unplugin 导出。在 StyleX 声明中使用应用 token 时,从 @lenso/tokens/tokens.stylex.const 导入。

Rolldown 使用官方集成,Next 使用官方 Babel/PostCSS 配置。源码扫描、SSR 与样式表导入要求见框架指南。

验证消费者

完整的项目创建、交互示例和开发/预览命令见 Vite 与 Rolldown。构建应用,打开生产路由,确认主题 CSS 与合并后的 StyleX 规则在控件呈现前已加载。检查本地 xstyle 覆盖与原生顶层覆盖层。开发环境样式可能掩盖生产 CSS 交付缺失。