An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file Runs REAL Vite production builds of fixture apps and asserts on the
* stylesheets they emit.
*
* The unit tests in vite.test.ts check the plugin's wiring, and they passed
* while the build shipped a version that wrapped every StyleX rule — Astryx's
* and the app's alike — in the library layer. That inverts the bug rather than
* fixing it: product styles are supposed to outrank a theme, and wrapped in
* `astryx-base` they lose to one. Only the built artifact shows it, so this
* builds one.
*
* Three shapes, because StyleX emits through two different paths and merges
* all entries into one stylesheet:
*
* `layer-split` the app imports a stylesheet, so the bundle has a
* CSS asset and StyleX appends in `generateBundle`
* `layer-split-nocss` the app imports none, so StyleX writes its own file
* in `writeBundle`, outside Rollup's graph
* `layer-split-multipage` two entries own distinct authored CSS, while both
* must load the one shared StyleX result
*
* The no-CSS shape was originally missing, which hid two defects: the split did
* not run there at all, and the file StyleX writes was not linked by any page.
* The multi-page shape protects against linking StyleX from only one entry or
* cross-loading that entry's authored CSS into every page.
*
* What none of this can prove is which declaration actually paints — that is a
* cascade fact, and it lives in .github/scripts/theme-layer-cascade.js.
*/
import {describe, it, expect, beforeAll, afterAll} from 'vitest';
import {build, createLogger} from 'vite';
import react from '@vitejs/plugin-react';
import {
mkdirSync,
mkdtempSync,
readdirSync,
readFileSync,
realpathSync,
rmSync,
symlinkSync,
writeFileSync,
} from 'node:fs';
import {tmpdir} from 'node:os';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
import {astryxStylex} from './vite';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const REPO_ROOT = path.resolve(__dirname, '../../..');
const FIXTURES = path.resolve(__dirname, '../__fixtures__');
const CORE_SRC = path.join(REPO_ROOT, 'packages/core/src');
const CORE_PACKAGE = path.join(REPO_ROOT, 'packages/core');
/** The class prefixes @astryxdesign/build/babel assigns per origin. */
const LIBRARY_CLASS = /\.astryx[a-z0-9]{5,}/g;
const PRODUCT_CLASS = /\.x[a-z0-9]{5,}/g;
type Built = {
css: string;
cssName: string;
cssByName: Record<string, string>;
html: string;
htmlByName: Record<string, string>;
outDir: string;
};
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}-`));
try {
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,
...(htmlNames.length > 1 && {
rollupOptions: {
input: Object.fromEntries(
htmlNames.map(file => [
path.basename(file, '.html'),
path.join(root, file),
]),
),
},
}),
},
resolve: {alias: {'@astryxdesign/core': CORE_SRC}},
plugins: [
react(),
...(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) {
rmSync(outDir, {recursive: true, force: true});
throw error;
}
const assets = path.join(outDir, 'assets');
const cssNames = readdirSync(assets).filter(f => f.endsWith('.css'));
const cssByName = Object.fromEntries(
cssNames.map(file => [
file,
readFileSync(path.join(assets, file), 'utf-8'),
]),
);
const cssName = cssNames.find(f => f.startsWith('astryx-stylex-'));
if (!cssName)
throw new Error(`no shared StyleX stylesheet emitted into ${assets}`);
const htmlByName = Object.fromEntries(
htmlNames.map(file => [
file,
readFileSync(path.join(outDir, file), 'utf-8'),
]),
);
return {
css: cssByName[cssName],
cssName,
cssByName,
html: htmlByName['index.html'],
htmlByName,
outDir,
};
}
/** The slice of a stylesheet inside a given top-level layer block. */
function layerBlock(css: string, name: string): string {
const start = css.indexOf(`@layer ${name} {`);
expect(
start,
`@layer ${name} is not in the emitted stylesheet`,
).toBeGreaterThan(-1);
let depth = 0;
for (let i = css.indexOf('{', start); i < css.length; i++) {
if (css[i] === '{') depth++;
else if (css[i] === '}' && --depth === 0) return css.slice(start, i + 1);
}
throw new Error(`@layer ${name} is unterminated`);
}
/** Both shapes must satisfy the same contract, so both run the same checks. */
function itSplitsCorrectly(get: () => Built) {
it('declares the layer order the split depends on', () => {
expect(get().html).toContain(
'@layer reset, astryx-base, astryx-theme, product;',
);
});
it("puts Astryx's own rules in the library layer", () => {
const library = layerBlock(get().css, 'astryx-base');
expect(library.match(LIBRARY_CLASS)?.length ?? 0).toBeGreaterThan(50);
// The fixture's Button pulls in real component CSS, so a token it styles
// with is a fact about this block rather than about class-name shape.
expect(library).toContain('--radius-element');
});
// The regression this file exists for. The wrapped-not-split version put the
// app's own StyleX in astryx-base, below `astryx-theme`, so a theme could
// silently restyle code the theme has no business reaching.
it("puts the app's own rules in the product layer, not the library one", () => {
const {css} = get();
const product = layerBlock(css, 'product');
const library = layerBlock(css, 'astryx-base');
expect(product).toContain('11px');
expect(library).not.toContain('11px');
expect(product.match(LIBRARY_CLASS)).toBeNull();
expect(library.match(PRODUCT_CLASS)).toBeNull();
});
it('keeps nested pseudo-elements and keyframes in the product layer', () => {
const product = layerBlock(get().css, 'product');
expect(product).toContain(':after');
expect(product).toContain('#010203');
expect(product).toContain('@keyframes');
expect(product).toContain('.717s');
});
it('leaves no StyleX rule outside the two layers', () => {
const {css} = get();
const outside = css
.replace(layerBlock(css, 'astryx-base'), '')
.replace(layerBlock(css, 'product'), '');
expect(outside).not.toContain('@layer priority');
});
// StyleX runs its CSS through lightningcss before emitting it. Replacing that
// output means running the same pass, or the build quietly loses the prefixes
// the original had.
it('keeps the vendor prefixing StyleX applies', () => {
// `-webkit-box-orient` is authored in source, so only a prefix the pass
// adds shows that it ran.
expect(get().css).toContain('-webkit-user-select');
});
// Source-built tokens must stay native at the same browser floor Astryx
// documents. Lowering `light-dark()` here rewrites root variables through
// mode helpers that exist only on Theme wrappers, so inherited data colors
// become invalid before a theme can use them.
it('preserves native light-dark() token values', () => {
const {css} = get();
expect(css).toContain('light-dark(');
expect(css).not.toContain('--lightningcss-light');
expect(css).not.toContain('--lightningcss-dark');
});
it('links the stylesheet from the page', () => {
const {html, cssName} = get();
expect(html).toContain(cssName);
expect(html.split(cssName).length - 1, 'linked more than once').toBe(1);
});
}
describe('a production build resolves generated locale modules', () => {
it('loads a generated string map through the standard Astryx Vite aliases', async () => {
const root = realpathSync(
mkdtempSync(path.join(tmpdir(), 'astryx-locale-import-')),
);
const packageDir = path.join(root, 'node_modules/@astryxdesign');
const outDir = path.join(root, 'dist');
mkdirSync(packageDir, {recursive: true});
symlinkSync(CORE_PACKAGE, path.join(packageDir, 'core'), 'dir');
writeFileSync(
path.join(root, 'index.html'),
'<script type="module" src="/main.ts"></script>',
);
writeFileSync(
path.join(root, 'main.ts'),
`import frFR from '@astryxdesign/core/locales/fr-FR.generated.js';\ndocument.body.textContent = frFR['@astryx.pagination.next'];\n`,
);
try {
await build({
root,
logLevel: 'error',
build: {outDir, emptyOutDir: true, minify: false},
plugins: [...astryxStylex({rootDir: root})],
});
const assets = path.join(outDir, 'assets');
const jsName = readdirSync(assets).find(file => file.endsWith('.js'));
expect(jsName).toBeTruthy();
expect(readFileSync(path.join(assets, jsName!), 'utf8')).toContain(
'Aller à la page suivante',
);
} finally {
rmSync(root, {recursive: true, force: true});
}
}, 180_000);
});
describe('a production build separates Astryx and product styles by layer', () => {
describe('when the app imports a stylesheet of its own', () => {
let built: Built;
beforeAll(async () => {
built = await buildFixture('layer-split');
}, 180_000);
afterAll(
() => built && rmSync(built.outDir, {recursive: true, force: true}),
);
itSplitsCorrectly(() => built);
});
// StyleX has no bundle asset to append to here, so it writes its own file in
// `writeBundle` — outside Rollup's graph, which is why Vite emits no `<link>`
// for it. Every assertion below failed before this case was handled: the
// stylesheet was unsplit AND the page loaded no styles at all.
describe('when the app imports no stylesheet at all', () => {
let built: Built;
beforeAll(async () => {
built = await buildFixture('layer-split-nocss');
}, 180_000);
afterAll(
() => built && rmSync(built.outDir, {recursive: true, force: true}),
);
itSplitsCorrectly(() => built);
});
describe('when the app has multiple HTML entries', () => {
let built: Built;
beforeAll(async () => {
built = await buildFixture('layer-split-multipage', [
'index.html',
'setup.html',
]);
}, 180_000);
afterAll(
() => built && rmSync(built.outDir, {recursive: true, force: true}),
);
it('links the shared StyleX stylesheet from every page exactly once', () => {
for (const html of Object.values(built.htmlByName)) {
expect(html).toContain(built.cssName);
expect(
html.split(built.cssName).length - 1,
'stylesheet is not linked exactly once',
).toBe(1);
}
});
it('keeps entry-owned CSS on its own page', () => {
const mainCss = Object.entries(built.cssByName).find(([, css]) =>
css.includes('--multipage-main-only'),
);
const setupCss = Object.entries(built.cssByName).find(([, css]) =>
css.includes('--multipage-setup-only'),
);
expect(mainCss).toBeDefined();
expect(setupCss).toBeDefined();
const [mainCssName] = mainCss!;
const [setupCssName] = setupCss!;
expect(built.htmlByName['index.html']).toContain(mainCssName);
expect(built.htmlByName['index.html']).not.toContain(setupCssName);
expect(built.htmlByName['setup.html']).toContain(setupCssName);
expect(built.htmlByName['setup.html']).not.toContain(mainCssName);
expect(built.css).not.toContain('--multipage-main-only');
expect(built.css).not.toContain('--multipage-setup-only');
});
});
});
// `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 compiles a swizzled copy in the library pass', () => {
let built: Built;
beforeAll(async () => {
built = await buildFixture('layer-split-swizzled', ['index.html'], {
zeroConfig: true,
});
}, 180_000);
afterAll(() => built && rmSync(built.outDir, {recursive: true, force: true}));
it('puts the copy under a swizzle marker in astryx-base, with the library prefix', () => {
const library = layerBlock(built.css, 'astryx-base');
expect(library).toContain('13px');
expect(library).toContain('#0a0b0c');
expect(library.match(PRODUCT_CLASS)).toBeNull();
expect(library.match(LIBRARY_CLASS)?.length ?? 0).toBeGreaterThan(0);
});
it("keeps the app's own rules in the product layer", () => {
const product = layerBlock(built.css, 'product');
expect(product).toContain('11px');
expect(product).not.toContain('13px');
});
});
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(
/borderTop is not supported.*borderTopWidth.*borderTopStyle.*borderTopColor/s,
);
}, 180_000);
});