Quick start
Install the React, theme and build packages, then deliver their compiled styles.
Requirements
Use React and React DOM versions that satisfy @lenso/ui's published peer ranges, and the official StyleX integration for your framework. Lenso does not require Tailwind.
Choose the build integration for Vite or Rolldown, or Next.js App Router. The steps below show the shared setup and a Vite configuration.
Packages
The React package is @lenso/ui; its theme and component style maps come from @lenso/tokens. Use a matching Lenso UI/tokens release. React and React DOM must satisfy the React package's published peer ranges.
npm install @lenso/ui @lenso/tokens @stylexjs/stylex@0.19.1
npm install -D @stylexjs/unplugin@0.19.1Using an unpublished candidate
Use the repository workspace or packed artifacts for an unpublished candidate. Check the contract's StyleX and framework versions before installing; these instructions do not establish publication.
Theme stylesheet
Load the stylesheet from the layout that actually renders the document:
// 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>,
);This entry supplies the light theme. Use theme="dark" for a dark scope. If replacing the Vite template entry, omit its starter index.css and App.css imports; retain your own application styles. UI SDK popups render in place in the browser's top layer and inherit this theme scope without a Portal part. If you create a custom portal, preserve its theme scope explicitly. A stylesheet loaded only by a sibling layout does not style this document.
The first screen can be a single native action:
// src/App.tsx
import { Button } from "@lenso/ui";
export default function App() {
return <Button onClick={() => console.log("Saved")}>Save changes</Button>;
}Complete the build integration below before relying on the component's production styling.
Application StyleX
Compile Lenso's shipped declarations and your application styles together with the official StyleX plugin:
// 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(),
],
});Keep optimizeDeps.exclude and the CommonJS optimizeDeps.include entries for development. Use the named unplugin export with the template's NodeNext configuration. Import application tokens from @lenso/tokens/tokens.stylex.const inside StyleX declarations.
Use the official Rolldown integration or Next Babel/PostCSS configuration for those frameworks. See Frameworks for source scanning, SSR and stylesheet ownership.
Verify a consumer
For a complete scaffold, interactive example and dev/preview commands, follow Vite and Rolldown. Build the application, open its production route, and check that both theme CSS and the combined StyleX rules load before the controls render. Exercise a local xstyle override and a top-layer overlay. Development styling can conceal missing production CSS delivery.