@astryxdesign/build 0.7.6-canary.f4abc97 → 0.7.6-canary.f52dbbe

package/README.md

@@ -239,6 +239,8 @@ Wraps `@stylexjs/unplugin` and intercepts the dev CSS endpoint (`/virtual:stylex
 
 Unsupported declarations fail the build by default with StyleX's replacement guidance. Set `propertyValidationMode` explicitly in `stylexOverrides` (modern API) or `stylexOptions` (legacy API) only when a migration needs the upstream `warn` or `silent` behavior.
 
+A production build also checks the StyleX stylesheet for generated custom properties (`--<prefix><hash>`) that it reads but no stylesheet in the build declares, which browsers drop: a `.stylex.ts` export read in a style that is not a `defineVars`/`defineConsts` value, or one whose module never reached the build. It warns, naming the variable and the rule that reads it. Only stylesheets count as declarations, so a property the app sets at runtime (an inline style) is reported too: give it a name outside the StyleX class-name prefixes.
+
 ---
 
 ## Advanced Options

package/dist/undefinedVariables.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file undefinedVariables.ts
+ * @input A stylesheet's text, the StyleX class-name prefixes, and the other
+ *   stylesheets the build emits
+ * @output undefinedGeneratedVariables, the generated custom properties the
+ *   stylesheet reads but never declares
+ * @position Internal to @astryxdesign/build: astryxStylex (vite.ts) runs it
+ *   on a production stylesheet and warns about what it finds. Not exported
+ *   from any package entry.
+ */
+/**
+ * The StyleX-generated custom properties `css` reads that it never declares.
+ *
+ * StyleX names the variables it generates `--<prefix><hash>` (a theme
+ * variable, or a constant waiting for its value). One that is read but never
+ * declared is a value that compiled to a variable nothing sets, so browsers
+ * drop the declaration or take its fallback: a constant whose defining module
+ * never reached the build, or a plain export read from a `.stylex.ts` file as
+ * if it were a token. The dynamic-style variables StyleX sets inline
+ * (`--<prefix>-<property>`) and component variables with a dash after the
+ * prefix are not generated names and are never reported.
+ *
+ * Only a hash-shaped name counts as generated: the prefix and four to seven
+ * base-36 characters (StyleX's hash is a 32-bit value in base 36, shorter than
+ * four characters about once in a hundred thousand). An app's own short names
+ * (`--xl`) are never reported, and a property declared in any stylesheet the
+ * build emits (`others`, the app's own CSS) is declared.
+ *
+ * SYNC: scripts/build-css.mjs `undefinedStyleXVariables` is the same check
+ * for the prebuilt package stylesheets.
+ */
+export declare function undefinedGeneratedVariables(css: string, prefixes: readonly string[], others?: readonly string[]): string[];

package/dist/vite.mjs

@@ -8,6 +8,26 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { createHash } from "node:crypto";
+
+// src/undefinedVariables.ts
+function undefinedGeneratedVariables(css, prefixes, others = []) {
+  const names = prefixes.map((prefix) => prefix.replace(/[^a-zA-Z0-9_-]/g, "")).filter(Boolean).join("|");
+  const declared = new Set(
+    [css, ...others].flatMap(
+      (text) => [...text.matchAll(/(--[A-Za-z0-9_-]+)\s*:/g)].map((match) => match[1])
+    )
+  );
+  const read = new Set(
+    [
+      ...css.matchAll(
+        new RegExp(`var\\(\\s*(--(?:${names})[a-z0-9]{4,7})\\s*[,)]`, "g")
+      )
+    ].map((match) => match[1])
+  );
+  return [...read].filter((name) => !declared.has(name)).sort();
+}
+
+// src/vite.ts
 var __dirname = path.dirname(fileURLToPath(import.meta.url));
 var LIBRARY_PATTERN = "node_modules/@astryxdesign/";
 var STYLEX_CSS_PATH = "/virtual:stylex.css";
@@ -32,6 +52,10 @@ function astryxStylex(options = {}) {
   } = opts;
   const libraryLayer = layers.library ?? "astryx-base";
   const productLayer = layers.product ?? "product";
+  const classNamePrefixes = [
+    stylexPrefix,
+    stylexOverrides.classNamePrefix ?? "x"
+  ];
   const overrideLightningcssOptions = stylexOverrides.lightningcssOptions;
   const stylexOptions = {
     dev,
@@ -148,7 +172,8 @@ function astryxStylex(options = {}) {
               renderSplitLayers(rulesById, {
                 libraryPattern,
                 libraryLayer,
-                productLayer
+                productLayer,
+                classNamePrefixes
               })
             );
           }
@@ -165,7 +190,8 @@ function astryxStylex(options = {}) {
       libraryPattern,
       libraryLayer,
       productLayer,
-      lightningcssOptions: stylexOptions.lightningcssOptions
+      lightningcssOptions: stylexOptions.lightningcssOptions,
+      classNamePrefixes
     })
   ];
 }
@@ -173,21 +199,57 @@ function renderSplitLayers(rulesById, options) {
   if (!rulesById || rulesById.size === 0) return "";
   const libraryRules = [];
   const productRules = [];
+  const collectedConstants = [];
   for (const [filePath, rules] of rulesById.entries()) {
-    if (filePath.includes(options.libraryPattern)) {
-      libraryRules.push(...rules);
-    } else {
-      productRules.push(...rules);
+    const own = filePath.includes(options.libraryPattern) ? libraryRules : productRules;
+    for (const rule of rules) {
+      if (isConstantRule(rule)) {
+        collectedConstants.push(rule);
+      } else {
+        own.push(rule);
+      }
     }
   }
+  const constantRules = constantRulesForEveryPrefix(
+    collectedConstants,
+    options.classNamePrefixes
+  );
   const render = (rules, layer) => rules.length ? `@layer ${layer} {
-${stylexBabelPlugin.processStylexRules(rules, { useLayers: true })}
+${stylexBabelPlugin.processStylexRules([...constantRules, ...rules], { useLayers: true })}
 }` : "";
   return [
     render(libraryRules, options.libraryLayer),
     render(productRules, options.productLayer)
   ].filter(Boolean).join("\n\n");
 }
+function constantRulesForEveryPrefix(rules, prefixes) {
+  const ordered = [...new Set(prefixes)].filter(Boolean).sort((a, b) => b.length - a.length);
+  const out = [];
+  const keys = /* @__PURE__ */ new Set();
+  const add = (rule, key) => {
+    if (keys.has(key)) return;
+    keys.add(key);
+    const [, body, ...rest] = rule;
+    out.push([key, { ...body, constKey: key }, ...rest]);
+  };
+  for (const rule of rules) {
+    const key = String(rule[1].constKey);
+    add(rule, key);
+    for (const prefix of ordered) {
+      const match = new RegExp(`^(|.*-)${prefix}([0-9a-z]+)$`).exec(key);
+      if (match == null) continue;
+      for (const other of ordered) {
+        add(rule, `${match[1]}${other}${match[2]}`);
+      }
+      break;
+    }
+  }
+  return out;
+}
+function isConstantRule(rule) {
+  const body = Array.isArray(rule) ? rule[1] : void 0;
+  return body?.constKey != null && body?.constVal != null;
+}
 function buildLayerSplitPlugin(basePlugin, options) {
   const stylex2 = basePlugin;
   let base = "/";
@@ -198,7 +260,7 @@ function buildLayerSplitPlugin(basePlugin, options) {
     configResolved(config) {
       base = config.base ?? "/";
     },
-    writeBundle(outputOptions) {
+    writeBundle(outputOptions, bundle) {
       const rulesById = stylex2.__stylexGetSharedStore?.().rulesById;
       if (!rulesById || rulesById.size === 0) return;
       const merged = stylex2.__stylexCollectCss?.();
@@ -207,6 +269,24 @@ function buildLayerSplitPlugin(basePlugin, options) {
         renderSplitLayers(rulesById, options),
         options.lightningcssOptions
       );
+      const emittedCss = Object.values(bundle).filter(
+        (output) => output.type === "asset" && output.fileName.endsWith(".css")
+      ).map(
+        (asset) => typeof asset.source === "string" ? asset.source : Buffer.from(asset.source).toString("utf8")
+      );
+      const undeclared = undefinedGeneratedVariables(
+        split,
+        options.classNamePrefixes,
+        emittedCss
+      );
+      if (undeclared.length > 0) {
+        this.warn(
+          `astryx-build-layer-split: the StyleX stylesheet reads ${undeclared.length} generated custom propert${undeclared.length === 1 ? "y" : "ies"} that no stylesheet in the build declares:
+` + undeclared.map(
+            (name) => `  ${name}, read by: ${rulesReading(split, name).join(" ") || "(rule not found)"}`
+          ).join("\n") + "\nWith no declaration, browsers drop the declarations that read it. A `.stylex.ts` export read in a style must be a `defineVars`/`defineConsts` value whose module reaches the build; a property the app sets at runtime (an inline style) needs a name outside the StyleX class-name prefixes."
+        );
+      }
       const outDir = outputOptions.dir ? outputOptions.dir : outputOptions.file ? path.dirname(outputOptions.file) : null;
       if (!outDir || !fs.existsSync(outDir)) return;
       const containingFiles = [];
@@ -247,6 +327,9 @@ function buildLayerSplitPlugin(basePlugin, options) {
     }
   };
 }
+function rulesReading(css, name) {
+  return [...css.matchAll(/[^{}]+\{[^{}]*\}/g)].map((match) => match[0].trim().replace(/\s+/g, " ")).filter((rule) => rule.includes(`var(${name}`)).slice(0, 3);
+}
 function listCssFiles(dir) {
   const out = [];
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -310,12 +393,24 @@ function astryxStylexLegacy(options) {
   const legacyLightningcssOptions = stylexOptions.lightningcssOptions;
   const validatedStylexOptions = {
     propertyValidationMode: "throw",
+    // The unplugin applies its Vite default (true) only to its own StyleX
+    // instance, which runs after the babel wrapper below has already compiled
+    // every StyleX call. Without it here, a file that reads only `defineConsts`
+    // from a `.stylex.ts` module loses that import once `stylex.create` is
+    // compiled (the TypeScript transform drops it as unused), the module is
+    // never loaded, and its constants never reach the CSS: a media-query key
+    // fails the build and a value ships as an undefined custom property.
+    treeshakeCompensation: true,
     ...stylexOptions,
     lightningcssOptions: {
       targets: LIGHTNINGCSS_TARGETS,
       ...legacyLightningcssOptions
     }
   };
+  const classNamePrefixes = [
+    stylexPrefix,
+    validatedStylexOptions.classNamePrefix ?? "x"
+  ];
   const astryxBabelPlugin = path.resolve(__dirname, "../src/babel.js");
   const existingPlugins = validatedStylexOptions.babelConfig?.plugins ?? [];
   const basePlugin = stylex.vite({
@@ -373,7 +468,8 @@ function astryxStylexLegacy(options) {
               renderSplitLayers(rulesById, {
                 libraryPattern,
                 libraryLayer,
-                productLayer
+                productLayer,
+                classNamePrefixes
               })
             );
           }
@@ -389,7 +485,8 @@ function astryxStylexLegacy(options) {
       libraryPattern,
       libraryLayer,
       productLayer,
-      lightningcssOptions: validatedStylexOptions.lightningcssOptions
+      lightningcssOptions: validatedStylexOptions.lightningcssOptions,
+      classNamePrefixes
     })
   ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/build",
-  "version": "0.7.6-canary.f4abc97",
+  "version": "0.7.6-canary.f52dbbe",
   "description": "Build plugins for Astryx source builds — babel, PostCSS, and Vite integrations",
   "author": "Meta Open Source",
   "license": "MIT",

package/src/undefinedVariables.ts

@@ -0,0 +1,57 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file undefinedVariables.ts
+ * @input A stylesheet's text, the StyleX class-name prefixes, and the other
+ *   stylesheets the build emits
+ * @output undefinedGeneratedVariables, the generated custom properties the
+ *   stylesheet reads but never declares
+ * @position Internal to @astryxdesign/build: astryxStylex (vite.ts) runs it
+ *   on a production stylesheet and warns about what it finds. Not exported
+ *   from any package entry.
+ */
+
+/**
+ * The StyleX-generated custom properties `css` reads that it never declares.
+ *
+ * StyleX names the variables it generates `--<prefix><hash>` (a theme
+ * variable, or a constant waiting for its value). One that is read but never
+ * declared is a value that compiled to a variable nothing sets, so browsers
+ * drop the declaration or take its fallback: a constant whose defining module
+ * never reached the build, or a plain export read from a `.stylex.ts` file as
+ * if it were a token. The dynamic-style variables StyleX sets inline
+ * (`--<prefix>-<property>`) and component variables with a dash after the
+ * prefix are not generated names and are never reported.
+ *
+ * Only a hash-shaped name counts as generated: the prefix and four to seven
+ * base-36 characters (StyleX's hash is a 32-bit value in base 36, shorter than
+ * four characters about once in a hundred thousand). An app's own short names
+ * (`--xl`) are never reported, and a property declared in any stylesheet the
+ * build emits (`others`, the app's own CSS) is declared.
+ *
+ * SYNC: scripts/build-css.mjs `undefinedStyleXVariables` is the same check
+ * for the prebuilt package stylesheets.
+ */
+export function undefinedGeneratedVariables(
+  css: string,
+  prefixes: readonly string[],
+  others: readonly string[] = [],
+): string[] {
+  const names = prefixes
+    .map(prefix => prefix.replace(/[^a-zA-Z0-9_-]/g, ''))
+    .filter(Boolean)
+    .join('|');
+  const declared = new Set(
+    [css, ...others].flatMap(text =>
+      [...text.matchAll(/(--[A-Za-z0-9_-]+)\s*:/g)].map(match => match[1]),
+    ),
+  );
+  const read = new Set(
+    [
+      ...css.matchAll(
+        new RegExp(`var\\(\\s*(--(?:${names})[a-z0-9]{4,7})\\s*[,)]`, 'g'),
+      ),
+    ].map(match => match[1]),
+  );
+  return [...read].filter(name => !declared.has(name)).sort();
+}

package/src/vite.build.test.ts

@@ -31,7 +31,7 @@
  */
 
 import {describe, it, expect, beforeAll, afterAll} from 'vitest';
-import {build} from 'vite';
+import {build, createLogger} from 'vite';
 import react from '@vitejs/plugin-react';
 import {
   mkdirSync,
@@ -70,6 +70,21 @@ type Built = {
 async function buildFixture(
   name: string,
   htmlNames: string[] = ['index.html'],
+  {
+    libraryPattern = 'packages/core/',
+    zeroConfig = false,
+    stylexOverrides,
+    warnings = [],
+  }: {
+    /** Which source paths land in the library layer. */
+    libraryPattern?: string;
+    /** Use `astryxStylex({...})` instead of the legacy `{stylexOptions}` form. */
+    zeroConfig?: boolean;
+    /** Zero-config form only: `stylexOverrides`. */
+    stylexOverrides?: Record<string, unknown>;
+    /** Receives every warning the build logs. */
+    warnings?: string[];
+  } = {},
 ): Promise<Built> {
   const root = path.join(FIXTURES, name);
   const outDir = mkdtempSync(path.join(tmpdir(), `astryx-${name}-`));
@@ -77,6 +92,11 @@ async function buildFixture(
     await build({
       root,
       logLevel: 'error',
+      customLogger: {
+        ...createLogger('error'),
+        warn: (message: string) => void warnings.push(message),
+        warnOnce: (message: string) => void warnings.push(message),
+      },
       build: {
         outDir,
         emptyOutDir: true,
@@ -94,17 +114,27 @@ async function buildFixture(
       resolve: {alias: {'@astryxdesign/core': CORE_SRC}},
       plugins: [
         react(),
-        ...astryxStylex({
-          stylexOptions: {
-            dev: false,
-            unstable_moduleResolution: {type: 'commonJS', rootDir: REPO_ROOT},
-            aliases: {
-              '@astryxdesign/core/*': [path.join(CORE_SRC, '*')],
-              '@astryxdesign/core': [CORE_SRC],
-            },
-          },
-          libraryPattern: 'packages/core/',
-        }),
+        ...(zeroConfig
+          ? astryxStylex({
+              dev: false,
+              rootDir: REPO_ROOT,
+              libraryPattern,
+              stylexOverrides,
+            })
+          : astryxStylex({
+              stylexOptions: {
+                dev: false,
+                unstable_moduleResolution: {
+                  type: 'commonJS',
+                  rootDir: REPO_ROOT,
+                },
+                aliases: {
+                  '@astryxdesign/core/*': [path.join(CORE_SRC, '*')],
+                  '@astryxdesign/core': [CORE_SRC],
+                },
+              },
+              libraryPattern,
+            })),
       ],
     });
   } catch (error) {
@@ -338,6 +368,105 @@ describe('a production build separates Astryx and product styles by layer', () =
   });
 });
 
+// `defineConsts` values are compiled into the reading file as placeholders,
+// `var(--<prefix><hash>)`, and the defining file contributes the values; the
+// final CSS pass substitutes one for the other. Both halves must reach that
+// pass. Storybook builds through the legacy `{stylexOptions}` form, whose
+// StyleX instance ran without `treeshakeCompensation`: once `stylex.create`
+// was compiled, nothing used the import at runtime, the TypeScript transform
+// dropped it, and the defining module was never loaded. A media-query key was
+// left as `var(--x…){…}` and failed the build ("Invalid empty selector"); a
+// value shipped as a custom property nothing defines. And a constant defined
+// on one side of the layer split and read on the other was substituted only
+// within its own side, and one an Astryx package defines (compiled with the
+// library class-name prefix) never matched an app file's placeholder (written
+// with the product prefix).
+describe('a production build resolves defineConsts imported across files', () => {
+  /** A constant reference StyleX left unsubstituted. */
+  const PLACEHOLDER = /var\(--(?:astryx|x)[a-z0-9]{4,}\)/;
+
+  for (const zeroConfig of [false, true]) {
+    describe(
+      zeroConfig ? 'zero-config form' : 'legacy stylexOptions form (Storybook)',
+      () => {
+        let built: Built;
+        beforeAll(async () => {
+          built = await buildFixture('stylex-consts', ['index.html'], {
+            libraryPattern: '__fixtures__/stylex-consts/library/',
+            zeroConfig,
+          });
+        }, 180_000);
+        afterAll(
+          () => built && rmSync(built.outDir, {recursive: true, force: true}),
+        );
+
+        it('substitutes a constant read as a value', () => {
+          expect(built.css).toMatch(/min-height:\s*52px/);
+        });
+
+        it('substitutes a constant read as a media-query key', () => {
+          expect(built.css).toMatch(
+            /@media \((?:max-width: ?599px|width ?<= ?599px)\)\s*\{[^}]*transition-property:\s*none/,
+          );
+        });
+
+        it('substitutes a library-side constant read from the product side', () => {
+          expect(built.css).toMatch(/padding-top:\s*13px/);
+          expect(built.css).toMatch(
+            /@media \((?:min-width: ?900px|width ?>= ?900px)\)\s*\{[^}]*max-width:\s*640px/,
+          );
+        });
+
+        it('substitutes a constant an Astryx package defines under the library prefix', () => {
+          expect(built.css).toMatch(/padding-bottom:\s*17px/);
+        });
+
+        it('leaves no constant placeholder behind', () => {
+          expect(built.css).not.toMatch(PLACEHOLDER);
+        });
+      },
+    );
+  }
+});
+
+describe('a production build checks the custom properties its stylesheet reads', () => {
+  const MESSAGE =
+    /reads 1 generated custom property that no stylesheet in the build declares[\s\S]*--x[a-z0-9]+, read by: [^\n]*row-gap/;
+
+  it('warns, naming the variable and the rule that reads it', async () => {
+    const warnings: string[] = [];
+    const built = await buildFixture('stylex-undefined-var', ['index.html'], {
+      warnings,
+    });
+    rmSync(built.outDir, {recursive: true, force: true});
+    expect(warnings.join('\n')).toMatch(MESSAGE);
+  }, 180_000);
+
+  it('checks the product prefix a zero-config build sets in stylexOverrides', async () => {
+    const warnings: string[] = [];
+    const built = await buildFixture('stylex-undefined-var', ['index.html'], {
+      zeroConfig: true,
+      stylexOverrides: {classNamePrefix: 'app'},
+      warnings,
+    });
+    rmSync(built.outDir, {recursive: true, force: true});
+    expect(warnings.join('\n')).toMatch(
+      /reads 1 generated custom property that no stylesheet in the build declares[\s\S]*--app[a-z0-9]+, read by: [^\n]*row-gap/,
+    );
+  }, 180_000);
+
+  it("never reports an app's own custom properties, declared in its own CSS", async () => {
+    const warnings: string[] = [];
+    const built = await buildFixture('stylex-app-vars', ['index.html'], {
+      warnings,
+    });
+    rmSync(built.outDir, {recursive: true, force: true});
+    expect(warnings.join('\n')).not.toMatch(
+      /no stylesheet in the build declares/,
+    );
+  }, 180_000);
+});
+
 describe('a production build validates StyleX declarations', () => {
   it('fails with longhand guidance instead of dropping a border shorthand', async () => {
     await expect(buildFixture('invalid-border')).rejects.toThrow(

package/src/vite.test.ts

@@ -14,6 +14,7 @@ import path from 'node:path';
 import {fileURLToPath, pathToFileURL} from 'node:url';
 import stylex from '@stylexjs/unplugin';
 import {astryxStylex, LIGHTNINGCSS_TARGETS} from './vite';
+import {undefinedGeneratedVariables} from './undefinedVariables';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -272,3 +273,57 @@ describe('astryxStylex optimizeDeps package discovery', () => {
     }
   });
 });
+
+describe('undefinedGeneratedVariables', () => {
+  it('reports a generated variable that is read but never declared', () => {
+    expect(
+      undefinedGeneratedVariables(
+        '.a{min-height:var(--astryx1abc2)}.b{color:var(--x9zz9z, red)}',
+        ['astryx', 'x'],
+      ),
+    ).toEqual(['--astryx1abc2', '--x9zz9z']);
+  });
+
+  it('accepts a variable declared anywhere in the stylesheet', () => {
+    expect(
+      undefinedGeneratedVariables(
+        ':root{--astryx1abc2:4px}.a{padding:var(--astryx1abc2)}',
+        ['astryx', 'x'],
+      ),
+    ).toEqual([]);
+  });
+
+  it('ignores dynamic-style and component variables, which carry a dash', () => {
+    expect(
+      undefinedGeneratedVariables(
+        '.a{width:var(--x-width)}.b{padding:var(--astryx-card-padding,8px)}',
+        ['astryx', 'x'],
+      ),
+    ).toEqual([]);
+  });
+
+  it('counts a declaration in any other stylesheet the build emits', () => {
+    expect(
+      undefinedGeneratedVariables(
+        '.a{padding:var(--xlarge)}',
+        ['astryx', 'x'],
+        [':root{--xlarge:24px}'],
+      ),
+    ).toEqual([]);
+  });
+
+  it('reports only hash-shaped names: four to seven characters after the prefix', () => {
+    expect(
+      undefinedGeneratedVariables(
+        '.a{margin:var(--xl)}.b{gap:var(--xs1)}.c{inset:var(--x1abc2de)}.d{top:var(--x1abc2def)}',
+        ['astryx', 'x'],
+      ),
+    ).toEqual(['--x1abc2de']);
+  });
+
+  it('checks only the prefixes it is given', () => {
+    expect(
+      undefinedGeneratedVariables('.a{color:var(--x1abc2)}', ['astryx']),
+    ).toEqual([]);
+  });
+});

package/src/vite.ts

@@ -8,6 +8,7 @@ import path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {createRequire} from 'node:module';
 import {createHash} from 'node:crypto';
+import {undefinedGeneratedVariables} from './undefinedVariables';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -136,6 +137,12 @@ export function astryxStylex(
 
   const libraryLayer = layers.library ?? 'astryx-base';
   const productLayer = layers.product ?? 'product';
+  // Library files compile with `stylexPrefix`, product files with StyleX's
+  // `classNamePrefix` (the babel wrapper routes them).
+  const classNamePrefixes = [
+    stylexPrefix,
+    (stylexOverrides as {classNamePrefix?: string}).classNamePrefix ?? 'x',
+  ];
 
   const overrideLightningcssOptions = (
     stylexOverrides as {lightningcssOptions?: Record<string, unknown>}
@@ -284,6 +291,7 @@ export function astryxStylex(
                 libraryPattern,
                 libraryLayer,
                 productLayer,
+                classNamePrefixes,
               }),
             );
           },
@@ -302,6 +310,7 @@ export function astryxStylex(
       libraryLayer,
       productLayer,
       lightningcssOptions: stylexOptions.lightningcssOptions,
+      classNamePrefixes,
     }),
   ];
 }
@@ -330,24 +339,43 @@ function renderSplitLayers(
     libraryPattern: string;
     libraryLayer: string;
     productLayer: string;
+    /** The StyleX class-name prefixes in play: library, then product. */
+    classNamePrefixes: readonly string[];
   },
 ): string {
   if (!rulesById || rulesById.size === 0) return '';
 
   const libraryRules: unknown[] = [];
   const productRules: unknown[] = [];
+  // `defineConsts` values. A file that reads a constant compiles it to a
+  // placeholder, `var(--<prefix><hash>)`, and `processStylexRules` substitutes
+  // the value from the defining file's rules, but only among the rules it is
+  // given. The defining file and the reading one can sit on opposite sides of
+  // the split, so every layer gets every constant, under every class-name
+  // prefix (see constantRulesForEveryPrefix). Constant rules emit no CSS of
+  // their own, so repeating them adds nothing to the output.
+  const collectedConstants: unknown[] = [];
 
   for (const [filePath, rules] of rulesById.entries()) {
-    if (filePath.includes(options.libraryPattern)) {
-      libraryRules.push(...rules);
-    } else {
-      productRules.push(...rules);
+    const own = filePath.includes(options.libraryPattern)
+      ? libraryRules
+      : productRules;
+    for (const rule of rules) {
+      if (isConstantRule(rule)) {
+        collectedConstants.push(rule);
+      } else {
+        own.push(rule);
+      }
     }
   }
 
+  const constantRules = constantRulesForEveryPrefix(
+    collectedConstants,
+    options.classNamePrefixes,
+  );
   const render = (rules: unknown[], layer: string) =>
     rules.length
-      ? `@layer ${layer} {\n${stylexBabelPlugin.processStylexRules(rules as never, {useLayers: true})}\n}`
+      ? `@layer ${layer} {\n${stylexBabelPlugin.processStylexRules([...constantRules, ...rules] as never, {useLayers: true})}\n}`
       : '';
 
   return [
@@ -358,6 +386,56 @@ function renderSplitLayers(
     .join('\n\n');
 }
 
+/**
+ * Each `defineConsts` rule once under every class-name prefix in play.
+ *
+ * StyleX keys a constant by its defining file's prefix, `<prefix><hash>` (or
+ * `<name>-<prefix><hash>` with debug class names), where the hash depends on
+ * the export and key alone, and a file that reads it writes the placeholder
+ * with its own prefix. An Astryx package compiles with the library prefix and
+ * an app with the product one, so an app reading a package's constant writes
+ * `var(--x<hash>)` while the package's rule is keyed `astryx<hash>`; the
+ * copies make every prefix's placeholder resolve. A key StyleX took verbatim
+ * (`'--name'`) carries no prefix and is kept as it is.
+ */
+function constantRulesForEveryPrefix(
+  rules: readonly unknown[],
+  prefixes: readonly string[],
+): unknown[] {
+  const ordered = [...new Set(prefixes)]
+    .filter(Boolean)
+    .sort((a, b) => b.length - a.length);
+  const out: unknown[] = [];
+  const keys = new Set<string>();
+  const add = (rule: unknown[], key: string) => {
+    if (keys.has(key)) return;
+    keys.add(key);
+    const [, body, ...rest] = rule;
+    out.push([key, {...(body as object), constKey: key}, ...rest]);
+  };
+  for (const rule of rules as unknown[][]) {
+    const key = String((rule[1] as {constKey: unknown}).constKey);
+    add(rule, key);
+    for (const prefix of ordered) {
+      const match = new RegExp(`^(|.*-)${prefix}([0-9a-z]+)$`).exec(key);
+      if (match == null) continue;
+      for (const other of ordered) {
+        add(rule, `${match[1]}${other}${match[2]}`);
+      }
+      break;
+    }
+  }
+  return out;
+}
+
+/** A `defineConsts` value as StyleX collects it: a rule with `constKey`/`constVal`. */
+function isConstantRule(rule: unknown): boolean {
+  const body = Array.isArray(rule)
+    ? (rule[1] as {constKey?: unknown; constVal?: unknown} | undefined)
+    : undefined;
+  return body?.constKey != null && body?.constVal != null;
+}
+
 /**
  * The build half of the split. StyleX appends one merged block of CSS to the
  * build's stylesheet, in its own top-level `@layer priority1…priorityN` — which
@@ -387,6 +465,8 @@ function buildLayerSplitPlugin(
     libraryLayer: string;
     productLayer: string;
     lightningcssOptions?: unknown;
+    /** The StyleX class-name prefixes in play: library, then product. */
+    classNamePrefixes: readonly string[];
   },
 ): Plugin {
   const stylex = basePlugin as {
@@ -402,7 +482,7 @@ function buildLayerSplitPlugin(
     configResolved(config) {
       base = config.base ?? '/';
     },
-    writeBundle(outputOptions) {
+    writeBundle(outputOptions, bundle) {
       const rulesById = stylex.__stylexGetSharedStore?.().rulesById;
       if (!rulesById || rulesById.size === 0) return;
 
@@ -414,6 +494,42 @@ function buildLayerSplitPlugin(
         options.lightningcssOptions,
       );
 
+      // An app's own stylesheets declare its own custom properties.
+      const emittedCss = Object.values(bundle)
+        .filter(
+          (output): output is Extract<typeof output, {type: 'asset'}> =>
+            output.type === 'asset' && output.fileName.endsWith('.css'),
+        )
+        .map(asset =>
+          typeof asset.source === 'string'
+            ? asset.source
+            : Buffer.from(asset.source).toString('utf8'),
+        );
+      const undeclared = undefinedGeneratedVariables(
+        split,
+        options.classNamePrefixes,
+        emittedCss,
+      );
+      if (undeclared.length > 0) {
+        this.warn(
+          'astryx-build-layer-split: the StyleX stylesheet reads ' +
+            `${undeclared.length} generated custom ` +
+            `propert${undeclared.length === 1 ? 'y' : 'ies'} ` +
+            'that no stylesheet in the build declares:\n' +
+            undeclared
+              .map(
+                name =>
+                  `  ${name}, read by: ${rulesReading(split, name).join(' ') || '(rule not found)'}`,
+              )
+              .join('\n') +
+            '\nWith no declaration, browsers drop the declarations that read ' +
+            'it. A `.stylex.ts` export read in a style must be a ' +
+            '`defineVars`/`defineConsts` value whose module reaches the build; ' +
+            'a property the app sets at runtime (an inline style) needs a name ' +
+            'outside the StyleX class-name prefixes.',
+        );
+      }
+
       const outDir = outputOptions.dir
         ? outputOptions.dir
         : outputOptions.file
@@ -472,6 +588,14 @@ function buildLayerSplitPlugin(
   };
 }
 
+/** The rules of `css` that read `name`, for the failure message. */
+function rulesReading(css: string, name: string): string[] {
+  return [...css.matchAll(/[^{}]+\{[^{}]*\}/g)]
+    .map(match => match[0].trim().replace(/\s+/g, ' '))
+    .filter(rule => rule.includes(`var(${name}`))
+    .slice(0, 3);
+}
+
 /** Every `.css` file under a directory, recursively. */
 function listCssFiles(dir: string): string[] {
   const out: string[] = [];
@@ -586,12 +710,25 @@ function astryxStylexLegacy(options: AstryxVitePluginLegacyOptions): Plugin[] {
   ).lightningcssOptions;
   const validatedStylexOptions = {
     propertyValidationMode: 'throw',
+    // The unplugin applies its Vite default (true) only to its own StyleX
+    // instance, which runs after the babel wrapper below has already compiled
+    // every StyleX call. Without it here, a file that reads only `defineConsts`
+    // from a `.stylex.ts` module loses that import once `stylex.create` is
+    // compiled (the TypeScript transform drops it as unused), the module is
+    // never loaded, and its constants never reach the CSS: a media-query key
+    // fails the build and a value ships as an undefined custom property.
+    treeshakeCompensation: true,
     ...(stylexOptions as any),
     lightningcssOptions: {
       targets: LIGHTNINGCSS_TARGETS,
       ...legacyLightningcssOptions,
     },
   };
+  const classNamePrefixes = [
+    stylexPrefix,
+    (validatedStylexOptions as {classNamePrefix?: string}).classNamePrefix ??
+      'x',
+  ];
   const astryxBabelPlugin = path.resolve(__dirname, 'babel.js');
   const existingPlugins = validatedStylexOptions.babelConfig?.plugins ?? [];
 
@@ -658,6 +795,7 @@ function astryxStylexLegacy(options: AstryxVitePluginLegacyOptions): Plugin[] {
                 libraryPattern,
                 libraryLayer,
                 productLayer,
+                classNamePrefixes,
               }),
             );
           },
@@ -677,6 +815,7 @@ function astryxStylexLegacy(options: AstryxVitePluginLegacyOptions): Plugin[] {
       lightningcssOptions: (
         validatedStylexOptions as {lightningcssOptions?: unknown}
       ).lightningcssOptions,
+      classNamePrefixes,
     }),
   ];
 }