An open source design system that's fully customizable and agent ready
TypeScript
fix: add cssMinify: false to all Vite configs to prevent light-dark() breakage (#623)
Cindy Zhangc99287c0ebf0
diff --git a/apps/example-nextjs/README.md b/apps/example-nextjs/README.mdindex 25e08f9e2d..70f0480e55 100644--- a/apps/example-nextjs/README.md+++ b/apps/example-nextjs/README.md@@ -127,6 +127,14 @@ export function Providers({children}) {| No `'use client'` on theme provider | Server component error from `createContext` | Mark the provider file with `'use client'` || StyleX as preset instead of plugin | Build errors or missing styles | Use `plugins` array, not `presets`, for `@stylexjs/babel-plugin` |+### ⚠️ CSS Minifiers and `light-dark()`++XDS tokens use the native CSS `light-dark()` function for theming. If you use a CSS minifier that "lowers" modern CSS (such as LightningCSS), it will convert `light-dark()` into `--lightningcss-light` / `--lightningcss-dark` polyfill variables that are never initialized — silently breaking all colors.++Next.js uses PostCSS for CSS processing (not LightningCSS), so this issue **does not apply** to the standard Next.js setup shown here. However, if you add a custom CSS minifier or use `next.config.mjs` experimental CSS features that invoke LightningCSS, you may encounter this. The safest approach is to avoid post-processing XDS-generated CSS through any tool that doesn't support native `light-dark()`.++For Vite-based setups, see the [Vite example's README](../example-vite/) for the specific fix (`cssMinify: false`).+## Related- [Issue #145 — Add example-nextjs project](https://github.com/facebookexperimental/xds/issues/145)diff --git a/apps/example-vite/README.md b/apps/example-vite/README.mdindex cc78e982b6..fbab0139e6 100644--- a/apps/example-vite/README.md+++ b/apps/example-vite/README.md@@ -37,6 +37,10 @@ import stylex from '@stylexjs/unplugin';const __dirname = path.dirname(fileURLToPath(import.meta.url));export default defineConfig({+ build: {+ // Prevent lightningcss from lowering light-dark() into broken polyfills+ cssMinify: false,+ },plugins: [stylex.vite({dev: process.env.NODE_ENV === 'development',@@ -109,12 +113,30 @@ npm run preview## Gotchas-| Issue | Symptom | Fix |-| ----------------------- | --------------------------------------- | ------------------------------------------------------------------------- |-| Missing resolve aliases | Module not found errors for `@xds/core` | Add `resolve.alias` pointing to source directory |-| Missing CSS entry point | StyleX has no CSS asset to append to | Create a minimal `index.css` and import it in `main.tsx` |-| Plugin order | Styles not extracted or HMR broken | `stylex.vite()` must come before `react()` in the plugins array |-| Duplicate React types | JSX component type errors in monorepo | Known monorepo issue with `@types/react` hoisting; doesn't affect runtime |+| Issue | Symptom | Fix |+| ------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------- |+| LightningCSS mangles light-dark | All colors invisible or broken theming | Add `build: { cssMinify: false }` — see below |+| Missing resolve aliases | Module not found errors for `@xds/core` | Add `resolve.alias` pointing to source directory |+| Missing CSS entry point | StyleX has no CSS asset to append to | Create a minimal `index.css` and import it in `main.tsx` |+| Plugin order | Styles not extracted or HMR broken | `stylex.vite()` must come before `react()` in the plugins array |+| Duplicate React types | JSX component type errors in monorepo | Known monorepo issue with `@types/react` hoisting; doesn't affect runtime |++### ⚠️ LightningCSS and `light-dark()`++XDS tokens use the native CSS `light-dark()` function for theming. Vite's default CSS minifier (LightningCSS) "lowers" `light-dark()` into `--lightningcss-light` / `--lightningcss-dark` polyfill variables. These polyfill variables are **never initialized**, so every color silently becomes empty — all theming breaks with no visible error.++**The fix is simple:** disable CSS minification in your Vite build config:++```ts+export default defineConfig({+ build: {+ cssMinify: false,+ },+ // ... plugins, resolve, etc.+});+```++This is safe because XDS dist CSS is already minified. Setting `lightningcssTargets` on the StyleX plugin is **not sufficient** — Vite's build-phase CSS minifier runs separately from the StyleX plugin and will still mangle `light-dark()` values.## Relateddiff --git a/apps/example-vite/vite.config.ts b/apps/example-vite/vite.config.tsindex b0b0a0ab73..9c24e4122e 100644--- a/apps/example-vite/vite.config.ts+++ b/apps/example-vite/vite.config.ts@@ -22,6 +22,13 @@ const lightningcssTargets = {// https://vite.dev/config/export default defineConfig({+ build: {+ // Don't use lightningcss for CSS minification — it lowers light-dark()+ // into --lightningcss-light/--lightningcss-dark polyfill variables that+ // are never initialized, silently breaking all XDS theming colors.+ // XDS dist CSS is already minified, so this costs nothing.+ cssMinify: false,+ },plugins: [stylex.vite({dev: process.env.NODE_ENV === 'development',diff --git a/apps/storybook/vite.config.ts b/apps/storybook/vite.config.tsindex 83a484904e..ffb18449b2 100644--- a/apps/storybook/vite.config.ts+++ b/apps/storybook/vite.config.ts@@ -16,6 +16,13 @@ const rootDir = path.resolve(__dirname, '../..');const coreRoot = path.resolve(__dirname, '../../packages/core/src');export default defineConfig({+ build: {+ // Don't use lightningcss for CSS minification — it lowers light-dark()+ // into --lightningcss-light/--lightningcss-dark polyfill variables that+ // are never initialized, silently breaking all XDS theming colors.+ // The pre-compiled dist CSS imported by preview.tsx is already minified.+ cssMinify: false,+ },plugins: [stylex.vite({// Use production mode with CSS extraction