An open source design system that's fully customizable and agent ready
TypeScript
feat(build): per-component CSS tree-shaking for dist path (#807)
Cindy Zhang6ea9a6dbf9e5
diff --git a/.gitignore b/.gitignoreindex eeacd95930..c709729b1e 100644--- a/.gitignore+++ b/.gitignore@@ -50,3 +50,4 @@ internal/vibe-tests/results/apps/sandbox/.next/apps/sandbox/out/apps/sandbox/next-env.d.ts+apps/example-nextjs-tailwind/.nextdiff --git a/apps/example-nextjs-tailwind/src/app/globals.css b/apps/example-nextjs-tailwind/src/app/globals.cssindex ee1eb28f6a..c51dd5ca9c 100644--- a/apps/example-nextjs-tailwind/src/app/globals.css+++ b/apps/example-nextjs-tailwind/src/app/globals.css@@ -1,4 +1,11 @@@import "tailwindcss";@import "@xds/core/reset.css";-@import "@xds/core/xds.css";@import "@xds/theme-default/theme.css";++/* Component CSS is now auto-imported via JS side-effect imports.+ * Each `import { XDSButton } from '@xds/core/Button'` pulls in+ * common.css (shared, loaded once) + Button/styles.css (unique).+ *+ * For the all-in-one approach, you can still use:+ * @import "@xds/core/xds.css";+ */diff --git a/packages/core/package.json b/packages/core/package.jsonindex 4847f760a3..3b0d65232a 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -415,7 +415,8 @@"lint": "eslint src","typecheck:docs": "tsc --project tsconfig.docs.json","build:css": "node ../../scripts/build-css.mjs",- "postbuild": "yarn build:css"+ "inject:css": "node ../../scripts/inject-css-imports.mjs",+ "postbuild": "yarn build:css && yarn inject:css"},"peerDependencies": {"react": ">=19.0.0",diff --git a/scripts/build-css.mjs b/scripts/build-css.mjsindex f6aab74b84..0cd92ff82f 100644--- a/scripts/build-css.mjs+++ b/scripts/build-css.mjs@@ -1,19 +1,24 @@/*** @file build-css.mjs* Post-build script that extracts StyleX CSS from compiled source files- * and outputs a single xds.css wrapped in @layer xds.core.base.+ * and outputs per-component CSS files, a shared common.css, and a combined xds.css,+ * all wrapped in @layer xds.** Usage: node scripts/build-css.mjs** This script:* 1. Runs Babel with the StyleX plugin over all source files- * 2. Collects the CSS rules StyleX generates- * 3. Wraps them in @layer xds.core.base { ... }- * 4. Writes to packages/core/dist/xds.css+ * 2. Groups CSS rules by component directory+ * 3. Identifies shared rules (used by 2+ components) → common.css+ * 4. Outputs per-component CSS files with only unique rules+ * 5. Outputs a combined xds.css with all rules+ * 6. All CSS is wrapped in @layer xds { ... }*- * The resulting CSS file can be imported by consumers who don't have- * StyleX in their build pipeline:+ * Per-component CSS enables tree-shaking for dist consumers:+ * import { Button } from '@xds/core/Button';+ * // bundler auto-includes common.css + dist/Button/styles.css*+ * All-in-one CSS for consumers who prefer a single import:* import '@xds/core/xds.css';*/@@ -29,8 +34,26 @@ const ROOT = path.resolve(__dirname, '..');const CORE_SRC = path.resolve(ROOT, 'packages/core/src');const CORE_DIST = path.resolve(ROOT, 'packages/core/dist');+/**+ * Determine which component a source file belongs to.+ * Returns the component directory name (e.g. "Button") or "_shared"+ * for files not in a component directory.+ */+function getComponentName(filePath) {+ const rel = path.relative(CORE_SRC, filePath);+ const parts = rel.split(path.sep);++ if (parts.length === 1) return '_shared';++ const dir = parts[0];+ if (dir[0] === dir[0].toUpperCase() && dir[0] !== '_') {+ return dir;+ }++ return '_shared';+}+async function collectStyleXCSS() {- // Find all TypeScript/TSX source filesconst files = await glob('**/*.{ts,tsx}', {cwd: CORE_SRC,absolute: true,@@ -39,12 +62,13 @@ async function collectStyleXCSS() {console.log(`Processing ${files.length} source files...`);+ // Map: componentName -> StyleX rules[]+ const componentRules = new Map();const allRules = [];for (const file of files) {const code = await fs.readFile(file, 'utf8');- // Skip files that don't use stylexif (!code.includes('@stylexjs/stylex')) {continue;}@@ -74,52 +98,191 @@ async function collectStyleXCSS() {],});- if (result?.metadata?.stylex) {- allRules.push(...result.metadata.stylex);+ if (result?.metadata?.stylex?.length) {+ const rules = result.metadata.stylex;+ const component = getComponentName(file);++ if (!componentRules.has(component)) {+ componentRules.set(component, []);+ }+ componentRules.get(component).push(...rules);+ allRules.push(...rules);}} catch (err) {- console.warn(` Warning: Could not process ${path.relative(ROOT, file)}: ${err.message}`);+ console.warn(+ ` Warning: Could not process ${path.relative(ROOT, file)}: ${err.message}`,+ );}}- console.log(`Collected ${allRules.length} StyleX rules`);+ console.log(`Collected ${allRules.length} StyleX rules across ${componentRules.size} groups`);- if (allRules.length === 0) {- console.warn('No StyleX rules found!');- return '';- }+ return {componentRules, allRules};+}- // Use StyleX's built-in CSS processor to sort and dedupe rules- const css = stylexBabelPlugin.processStylexRules(allRules, false);+/**+ * Given a list of StyleX rules, produce CSS via the official processor+ * and parse it into individual rule entries: { className, rule (full text) }+ */+function parseRulesFromCSS(css) {+ const entries = [];+ // Match each rule: .className...{ ... }+ // StyleX rules can have :not(#\#) and pseudo-selectors+ const ruleRegex = /(\.[a-z][a-z0-9_-]+[^{}]*)\{([^}]+)\}/g;+ let match;+ while ((match = ruleRegex.exec(css)) !== null) {+ const selector = match[1].trim();+ const className = selector.match(/^(\.[a-z][a-z0-9_-]+)/)?.[1];+ if (className) {+ entries.push({className, fullRule: match[0]});+ }+ }+ return entries;+}- // Wrap in @layer xds.core.base- const layeredCSS = `/* XDS Pre-compiled StyleX CSS */-/* This file is auto-generated. Do not edit manually. */-/* Consumer styles (unlayered) always override these styles. */+function wrapInLayer(css, comment) {+ if (!css.trim()) return '';+ return `/* ${comment} */+/* Auto-generated. Do not edit manually. */-@layer xds.core.base {-${css.split('\n').map(line => ' ' + line).join('\n')}+@layer xds {+${css+ .split('\n')+ .map(line => ' ' + line)+ .join('\n')}}`;-- return layeredCSS;}async function main() {- const css = await collectStyleXCSS();+ const {componentRules, allRules} = await collectStyleXCSS();- if (!css) {- console.error('Failed to collect CSS');+ if (allRules.length === 0) {+ console.error('No StyleX rules found!');process.exit(1);}- // Ensure dist directory existsawait fs.mkdir(CORE_DIST, {recursive: true});- const outPath = path.resolve(CORE_DIST, 'xds.css');- await fs.writeFile(outPath, css, 'utf8');- console.log(`\nWritten to ${path.relative(ROOT, outPath)}`);- console.log(`Size: ${(css.length / 1024).toFixed(1)} KB`);+ // --- Step 1: Process each component's rules to get CSS ---+ // We need to identify which CSS classes are shared across components.+ // Process each component independently, then compare.+ const componentCSS = new Map(); // component -> parsed CSS entries+ const classToComponents = new Map(); // className -> Set<component>+ const classToRule = new Map(); // className -> full rule text (first seen)++ for (const [component, rules] of componentRules) {+ if (component === '_shared' || rules.length === 0) continue;++ const css = stylexBabelPlugin.processStylexRules(rules, false);+ if (!css.trim()) continue;++ const entries = parseRulesFromCSS(css);+ componentCSS.set(component, entries);++ for (const {className, fullRule} of entries) {+ if (!classToComponents.has(className)) {+ classToComponents.set(className, new Set());+ }+ classToComponents.get(className).add(component);++ if (!classToRule.has(className)) {+ classToRule.set(className, fullRule);+ }+ }+ }++ // --- Step 2: Identify shared classes (2+ components) ---+ const sharedClasses = new Set();+ for (const [className, components] of classToComponents) {+ if (components.size >= 2) {+ sharedClasses.add(className);+ }+ }++ console.log(`\nShared classes (2+ components): ${sharedClasses.size}`);+ console.log(`Unique classes: ${classToComponents.size - sharedClasses.size}`);++ // --- Step 3: Write common.css with shared rules ---+ // Use the combined allRules processed output to get correct ordering+ const combinedCSS = stylexBabelPlugin.processStylexRules(allRules, false);+ const combinedEntries = parseRulesFromCSS(combinedCSS);++ const commonRules = combinedEntries+ .filter(e => sharedClasses.has(e.className))+ .map(e => e.fullRule);++ // Dedupe (same className can appear in multiple @media contexts)+ const seenCommon = new Set();+ const dedupedCommonRules = commonRules.filter(rule => {+ if (seenCommon.has(rule)) return false;+ seenCommon.add(rule);+ return true;+ });++ const commonCSSContent = dedupedCommonRules.join('\n');+ const commonPath = path.resolve(CORE_DIST, 'common.css');+ await fs.writeFile(+ commonPath,+ wrapInLayer(commonCSSContent, 'XDS shared styles — auto-imported by components'),+ 'utf8',+ );+ console.log(`Common CSS: ${(commonCSSContent.length / 1024).toFixed(1)} KB (${dedupedCommonRules.length} rules)`);++ // --- Step 4: Write per-component CSS (unique rules only) ---+ let componentCount = 0;+ const manifest = {};++ for (const [component, entries] of componentCSS) {+ // Filter to only rules unique to this component+ const uniqueRules = entries+ .filter(e => !sharedClasses.has(e.className))+ .map(e => e.fullRule);++ const componentDir = path.resolve(CORE_DIST, component);+ await fs.mkdir(componentDir, {recursive: true});++ const outPath = path.resolve(componentDir, 'styles.css');++ if (uniqueRules.length === 0) {+ // Component only uses shared classes — still write an empty-ish file+ // so the import doesn't break+ await fs.writeFile(+ outPath,+ `/* XDS ${component} styles */\n/* All rules for this component are in common.css */\n`,+ 'utf8',+ );+ } else {+ // Dedupe within component+ const seen = new Set();+ const deduped = uniqueRules.filter(rule => {+ if (seen.has(rule)) return false;+ seen.add(rule);+ return true;+ });+ await fs.writeFile(outPath, wrapInLayer(deduped.join('\n'), `XDS ${component} styles`), 'utf8');+ }++ manifest[component] = {total: entries.length, unique: uniqueRules.length};+ componentCount++;+ }++ console.log(`\nWrote ${componentCount} per-component CSS files`);++ // --- Step 5: Write combined xds.css ---+ const combinedPath = path.resolve(CORE_DIST, 'xds.css');+ await fs.writeFile(+ combinedPath,+ wrapInLayer(combinedCSS, 'XDS Pre-compiled StyleX CSS — all components'),+ 'utf8',+ );+ console.log(`Combined: ${(combinedCSS.length / 1024).toFixed(1)} KB`);++ // --- Manifest ---+ const manifestLines = Object.entries(manifest)+ .sort(([a], [b]) => a.localeCompare(b))+ .map(([name, {total, unique}]) => ` ${name}: ${unique} unique / ${total} total`);+ console.log(`\nPer-component breakdown:\n${manifestLines.join('\n')}`);}main().catch(err => {diff --git a/scripts/inject-css-imports.mjs b/scripts/inject-css-imports.mjsnew file mode 100644index 0000000000..ee5331b8d8--- /dev/null+++ b/scripts/inject-css-imports.mjs@@ -0,0 +1,72 @@+/**+ * @file inject-css-imports.mjs+ * Post-build script that adds CSS imports to each component's dist JS+ * entry point, enabling automatic CSS tree-shaking.+ *+ * Injects:+ * import '../common.css'; // shared atomic classes+ * import './styles.css'; // component-specific classes+ *+ * Usage: node scripts/inject-css-imports.mjs+ *+ * Runs after build-css.mjs. The common.css import is deduplicated by+ * bundlers — even though every component imports it, the bundler only+ * includes it once in the output.+ */++import fs from 'fs/promises';+import path from 'path';+import {fileURLToPath} from 'url';++const __dirname = path.dirname(fileURLToPath(import.meta.url));+const ROOT = path.resolve(__dirname, '..');+const CORE_DIST = path.resolve(ROOT, 'packages/core/dist');++async function main() {+ const entries = await fs.readdir(CORE_DIST, {withFileTypes: true});+ let injected = 0;+ let skipped = 0;++ // Verify common.css exists+ try {+ await fs.access(path.join(CORE_DIST, 'common.css'));+ } catch {+ console.error('common.css not found in dist — run build-css.mjs first');+ process.exit(1);+ }++ for (const entry of entries) {+ if (!entry.isDirectory()) continue;++ const cssPath = path.join(CORE_DIST, entry.name, 'styles.css');+ const mjsPath = path.join(CORE_DIST, entry.name, 'index.mjs');++ // Only inject if both styles.css and index.mjs exist+ try {+ await fs.access(cssPath);+ await fs.access(mjsPath);+ } catch {+ skipped++;+ continue;+ }++ const content = await fs.readFile(mjsPath, 'utf8');++ // Don't double-inject+ if (content.includes("import '../common.css'")) {+ skipped++;+ continue;+ }++ const imports = `import '../common.css';\nimport './styles.css';\n`;+ await fs.writeFile(mjsPath, `${imports}${content}`, 'utf8');+ injected++;+ }++ console.log(`Injected CSS imports into ${injected} component entry points (${skipped} skipped)`);+}++main().catch(err => {+ console.error(err);+ process.exit(1);+});