An open source design system that's fully customizable and agent ready
TypeScript
feat(build): streamline xdsStylex() Vite API (#2227)
Cindy Zhanga2c8b2e8ed7c
diff --git a/apps/example-vite/src/App.tsx b/apps/example-vite/src/App.tsxindex cd0153487c..5707dd66fb 100644--- a/apps/example-vite/src/App.tsx+++ b/apps/example-vite/src/App.tsx@@ -9,7 +9,7 @@ import {XDSButton} from '@xds/core/Button';import {XDSText, XDSHeading} from '@xds/core/Text';import {XDSTextInput} from '@xds/core/TextInput';import {XDSBadge} from '@xds/core/Badge';-import {XDSDivider} from '@xds/core';+import {XDSDivider} from '@xds/core/Divider';const styles = stylex.create({main: {diff --git a/apps/example-vite/vite.config.ts b/apps/example-vite/vite.config.tsindex 913ad37ca3..15842245d7 100644--- a/apps/example-vite/vite.config.ts+++ b/apps/example-vite/vite.config.ts@@ -1,51 +1,9 @@// Copyright (c) Meta Platforms, Inc. and affiliates.-import path from 'path';-import {fileURLToPath} from 'url';import {defineConfig} from 'vite';import react from '@vitejs/plugin-react';import {xdsStylex} from '@xds/build/vite';-const __dirname = path.dirname(fileURLToPath(import.meta.url));--/**- * Browser targets for lightningcss.- * Prevents lowering native light-dark() into polyfill variables.- */-const lightningcssTargets = {- chrome: 123 << 16,- firefox: 120 << 16,- safari: (17 << 16) | (5 << 8),-};-export default defineConfig({- plugins: [- ...xdsStylex({- stylexOptions: {- dev: process.env.NODE_ENV === 'development',- runtimeInjection: false,- treeshakeCompensation: true,- unstable_moduleResolution: {- type: 'commonJS',- rootDir: __dirname,- },- lightningcssOptions: {- targets: lightningcssTargets,- },- },- }),- react(),- ],- resolve: {- alias: {- '@xds/core/theme/tokens.stylex': path.resolve(- __dirname,- 'node_modules/@xds/core/src/theme/tokens.stylex.ts',- ),- '@xds/core': path.resolve(__dirname, 'node_modules/@xds/core/src'),- },- },- optimizeDeps: {- exclude: ['@xds/core', '@xds/theme-default'],- },+ plugins: [...xdsStylex(), react()],});diff --git a/packages/build/build.mjs b/packages/build/build.mjsindex fdda359e5c..5a227c1edd 100644--- a/packages/build/build.mjs+++ b/packages/build/build.mjs@@ -32,7 +32,7 @@ buildSync({// Fix babel.js path: dist/vite.mjs resolves __dirname to dist/,// but babel.js lives in src/let content = readFileSync('dist/vite.mjs', 'utf8');-content = content.replace(+content = content.replaceAll('resolve(__dirname, "babel.js")','resolve(__dirname, "../src/babel.js")',);diff --git a/packages/build/src/vite.ts b/packages/build/src/vite.tsindex 0d05fd3947..9bb9c1dc51 100644--- a/packages/build/src/vite.ts+++ b/packages/build/src/vite.ts@@ -1,6 +1,6 @@// Copyright (c) Meta Platforms, Inc. and affiliates.-import type {Plugin} from 'vite';+import type {Plugin, UserConfig} from 'vite';import stylexBabelPlugin from '@stylexjs/babel-plugin';import stylex from '@stylexjs/unplugin';import path from 'path';@@ -11,12 +11,42 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));const XDS_LIBRARY_PATTERN = 'node_modules/@xds/';const STYLEX_CSS_PATH = '/virtual:stylex.css';+/**+ * Browser targets for lightningcss (opt-in).+ * Only needed if your StyleX version lowers light-dark() without them.+ * Exported for consumers who want to opt in explicitly.+ */+export const LIGHTNINGCSS_TARGETS = {+ chrome: 123 << 16,+ firefox: 120 << 16,+ safari: (17 << 16) | (5 << 8),+};++/**+ * Legacy options shape — kept for backward compatibility.+ * Prefer the zero-config form: xdsStylex()+ */+export interface XDSVitePluginLegacyOptions {+ stylexOptions: Parameters<typeof stylex.vite>[0];+ libraryPattern?: string;+ layers?: {+ library?: string;+ product?: string;+ };+}+export interface XDSVitePluginOptions {/**- * Options passed to @stylexjs/unplugin.- * See https://stylexjs.com/docs/api/configuration/babel-plugin/+ * Whether to enable dev mode for StyleX.+ * @default process.env.NODE_ENV !== 'production'*/- stylexOptions: Parameters<typeof stylex.vite>[0];+ dev?: boolean;++ /**+ * Root directory for module resolution.+ * @default process.cwd()+ */+ rootDir?: string;/*** Pattern to identify XDS library files vs product files.@@ -33,33 +63,235 @@ export interface XDSVitePluginOptions {/** Layer name for product styles @default 'product' */product?: string;};++ /**+ * LightningCSS browser targets. Only needed if your StyleX version+ * lowers light-dark() without them. Most recent versions preserve+ * light-dark() by default.+ * @default undefined (no targets set)+ */+ lightningcssTargets?: Record<string, number>;++ /**+ * Extra StyleX options to merge.+ */+ stylexOverrides?: Record<string, unknown>;}/**- * Vite plugin for XDS source builds.+ * XDS Vite plugin for source builds.*- * Wraps @stylexjs/unplugin to compile StyleX from both XDS library source- * and product code, then splits the CSS output into separate named layers:+ * Provides sensible defaults for StyleX compilation with XDS.+ * Just spread into your plugins array:*- * reset < xds-base (library) < xds-theme < product (app)+ * plugins: [...xdsStylex(), react()]*- * The babel wrapper plugin (@xds/build/babel) is injected into the- * unplugin's babelConfig.plugins so it runs BEFORE the hardcoded- * StyleX instance. Our wrapper transforms stylex.create() calls with- * the correct prefix per file, leaving nothing for the stock instance.+ * Handles:+ * - StyleX compilation with correct settings+ * - CSS layer ordering (reset < xds-base < xds-theme < product)+ * - resolve.alias for @xds/core source+ * - optimizeDeps.exclude to prevent Vite pre-bundling XDS+ *+ * @param options — optional overrides*/-export function xdsStylex(options: XDSVitePluginOptions): Plugin[] {+export function xdsStylex(options: XDSVitePluginOptions | XDSVitePluginLegacyOptions = {}): Plugin[] {+ // Detect legacy API: xdsStylex({stylexOptions: {...}})+ if ('stylexOptions' in options && options.stylexOptions) {+ return xdsStylexLegacy(options as XDSVitePluginLegacyOptions);+ }++ const opts = options as XDSVitePluginOptions;const {- stylexOptions,+ dev = process.env.NODE_ENV !== 'production',+ rootDir = process.cwd(),libraryPattern = XDS_LIBRARY_PATTERN,layers = {},- } = options;+ lightningcssTargets,+ stylexOverrides = {},+ } = opts;const libraryLayer = layers.library ?? 'xds-base';const productLayer = layers.product ?? 'product';+ // Build StyleX options with sensible defaults+ const stylexOptions: Record<string, unknown> = {+ dev,+ runtimeInjection: false,+ treeshakeCompensation: true,+ unstable_moduleResolution: {+ type: 'commonJS',+ rootDir,+ },+ ...(lightningcssTargets && {+ lightningcssOptions: {targets: lightningcssTargets},+ }),+ ...stylexOverrides,+ };+// Inject our babel wrapper as a user plugin — it runs before the// unplugin's hardcoded StyleX instance and handles prefix routing.+ const xdsBabelPlugin = path.resolve(__dirname, 'babel.js');++ const basePlugin = stylex.vite({+ ...(stylexOptions as any),+ useCSSLayers: true,+ babelConfig: {+ plugins: [+ [+ xdsBabelPlugin,+ {+ ...stylexOptions,+ babelConfig: undefined,+ },+ ],+ ],+ },+ });++ // Layer order declaration plugin+ const layerOrderPlugin: Plugin = {+ name: 'xds-css-layer-order',+ transformIndexHtml() {+ return [+ {+ tag: 'style',+ children: `@layer reset, ${libraryLayer}, xds-theme, ${productLayer};`,+ injectTo: 'head-prepend',+ },+ ];+ },+ };++ // Config plugin — injects resolve.alias and optimizeDeps+ const configPlugin: Plugin = {+ name: 'xds-config',+ config(): UserConfig {+ // Discover all @xds/* packages to exclude from pre-bundling.+ // XDS ships as source that must be compiled by StyleX — pre-bundling+ // strips stylex.create/defineVars calls and causes runtime errors.+ let xdsPackages: string[] = ['@xds/core'];+ try {+ const fs = require('fs');+ const xdsDir = path.resolve(rootDir, 'node_modules/@xds');+ if (fs.existsSync(xdsDir)) {+ xdsPackages = fs.readdirSync(xdsDir)+ .filter((name: string) => !name.startsWith('.'))+ .map((name: string) => `@xds/${name}`);+ }+ } catch {+ // Fallback to just @xds/core if discovery fails+ }++ return {+ resolve: {+ alias: {+ '@xds/core/theme/tokens.stylex': path.resolve(+ rootDir,+ 'node_modules/@xds/core/src/theme/tokens.stylex.ts',+ ),+ '@xds/core': path.resolve(rootDir, 'node_modules/@xds/core/src'),+ },+ },+ optimizeDeps: {+ exclude: xdsPackages,+ },+ };+ },+ };++ // Split-layer interceptor plugin (dev server only)+ const splitLayerPlugin: Plugin = {+ name: 'xds-split-layers',+ configureServer(server) {+ let stylexPlugin: any = null;++ return () => {+ for (const p of server.config.plugins.flat()) {+ if ((p as any)?.__stylexGetSharedStore) {+ stylexPlugin = p;+ break;+ }+ }++ server.middlewares.stack.unshift({+ route: '',+ handle: (req: any, res: any, next: any) => {+ if (!req.url?.startsWith(STYLEX_CSS_PATH)) {+ return next();+ }++ if (!stylexPlugin) {+ res.statusCode = 200;+ res.setHeader('Content-Type', 'text/css');+ res.end('');+ return;+ }++ const shared = stylexPlugin.__stylexGetSharedStore?.();+ const rulesById = shared?.rulesById;++ if (!rulesById || rulesById.size === 0) {+ res.statusCode = 200;+ res.setHeader('Content-Type', 'text/css');+ res.end('');+ return;+ }++ const libraryRules: any[] = [];+ const productRules: any[] = [];++ for (const [filePath, rules] of rulesById.entries()) {+ if (filePath.includes(libraryPattern)) {+ libraryRules.push(...rules);+ } else {+ productRules.push(...rules);+ }+ }++ const libraryCss = libraryRules.length+ ? stylexBabelPlugin.processStylexRules(libraryRules, {+ useLayers: true,+ })+ : '';+ const productCss = productRules.length+ ? stylexBabelPlugin.processStylexRules(productRules, {+ useLayers: true,+ })+ : '';++ const parts: string[] = [];+ if (libraryCss)+ parts.push(`@layer ${libraryLayer} {\n${libraryCss}\n}`);+ if (productCss)+ parts.push(`@layer ${productLayer} {\n${productCss}\n}`);++ res.statusCode = 200;+ res.setHeader('Content-Type', 'text/css');+ res.setHeader('Cache-Control', 'no-store');+ res.end(parts.join('\n\n'));+ },+ });+ };+ },+ };++ return [configPlugin, layerOrderPlugin, basePlugin, splitLayerPlugin];+}++/**+ * Legacy implementation — handles the old xdsStylex({stylexOptions: {...}}) API.+ * Used by Storybook and other existing configs.+ */+function xdsStylexLegacy(options: XDSVitePluginLegacyOptions): Plugin[] {+ const {+ stylexOptions,+ libraryPattern = XDS_LIBRARY_PATTERN,+ layers = {},+ } = options;++ const libraryLayer = layers.library ?? 'xds-base';+ const productLayer = layers.product ?? 'product';+const xdsBabelPlugin = path.resolve(__dirname, 'babel.js');const existingPlugins = stylexOptions.babelConfig?.plugins ?? [];@@ -73,7 +305,6 @@ export function xdsStylex(options: XDSVitePluginOptions): Plugin[] {xdsBabelPlugin,{...(stylexOptions as any),- // Remove babelConfig to avoid circular referencebabelConfig: undefined,},],@@ -82,7 +313,6 @@ export function xdsStylex(options: XDSVitePluginOptions): Plugin[] {},});- // Layer order declaration pluginconst layerOrderPlugin: Plugin = {name: 'xds-css-layer-order',transformIndexHtml() {@@ -96,7 +326,6 @@ export function xdsStylex(options: XDSVitePluginOptions): Plugin[] {},};- // Split-layer interceptor pluginconst splitLayerPlugin: Plugin = {name: 'xds-split-layers',configureServer(server) {