Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

refactor(storybook): derive workspace aliases from one table (#6299)

Jiun Shin4f5e785d42b1
diff --git a/apps/storybook/.storybook/main.test.ts b/apps/storybook/.storybook/main.test.ts
index eccce93147..c63b484479 100644
--- a/apps/storybook/.storybook/main.test.ts
+++ b/apps/storybook/.storybook/main.test.ts
@@ -2,22 +2,28 @@
/**
* @file main.test.ts
+ * @input Storybook config, workspace alias table, and app package dependencies.
+ * @output Regression coverage for source aliases and cold-clone config loading.
+ * @position Node tests beside the Storybook configuration.
* @description Guards two things that both keep `storybook dev` working from
* a cold clone, at two different resolution stages.
*
- * 1. Vite's module graph: every `@astryxdesign/*` dependency of this app
+ * 1. Vite's module graph: every runtime `@astryxdesign/*` dependency
* must be aliased to package source in `.storybook/main.ts`. Without an
* alias, Vite resolves the workspace link through the package's export
* map, which points at `dist/` build output that does not exist in a
* fresh worktree — `storybook dev` then fails its dependency scan
- * (#5092: `@astryxdesign/richtext`).
+ * (#5092: `@astryxdesign/richtext`). The same table feeds StyleX while
+ * preserving theme wildcard-only aliases and Vega's lack of StyleX imports.
* 2. Storybook's own config loader: `main.ts` is evaluated by Node's ESM
* resolver before any alias from it is in play, so the specifiers
* `main.ts` itself imports must also resolve unbuilt (#5128:
* `@astryxdesign/build/vite` → `dist/vite.mjs`).
*/
-import {describe, it, expect} from 'vitest';
+import {afterAll, beforeAll, describe, it, expect, vi} from 'vitest';
+import * as build from '../../../packages/build/src/vite.ts';
+import config, {workspaceAliases} from './main.ts';
import {existsSync, readFileSync} from 'node:fs';
import path from 'node:path';
import {fileURLToPath} from 'node:url';
@@ -29,9 +35,11 @@ const pkg = JSON.parse(
readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'),
) as {dependencies?: Record<string, string>};
-// The Vite `resolve.alias` block only — the StyleX `aliases` block above it
-// carries the same keys but does not drive Vite's dev-mode resolution.
-const viteAliasBlock = mainTs.slice(mainTs.indexOf('alias: {'));
+const rootDir = path.resolve(__dirname, '../../..');
+// viteFinal only consumes Vite's config; the Storybook loader options are unused.
+const storybookOptions = {} as Parameters<
+ NonNullable<typeof config.viteFinal>
+>[1];
const workspaceDeps = Object.keys(pkg.dependencies ?? {}).filter(name =>
name.startsWith('@astryxdesign/'),
@@ -47,15 +55,77 @@ const runtimeImports = [
].map(match => match[1]);
describe('storybook main.ts workspace source aliases', () => {
- it('sees the @astryxdesign workspace dependencies', () => {
+ let viteAliases: Record<string, string>;
+ let stylexAliases: Record<string, string[]>;
+ const stylexSpy = vi.spyOn(build, 'astryxStylex');
+
+ beforeAll(async () => {
+ // Call through to the real plugin so these assertions cover the options
+ // consumed by StyleX as well as the config Vite receives.
+ const viteConfig = await config.viteFinal!({}, storybookOptions);
+ viteAliases = viteConfig.resolve!.alias as Record<string, string>;
+ const options = stylexSpy.mock.lastCall![0];
+ if (!options || !('stylexOptions' in options)) {
+ throw new Error('Expected the Storybook StyleX options');
+ }
+ stylexAliases = options.stylexOptions!.aliases as Record<string, string[]>;
+ });
+
+ afterAll(() => stylexSpy.mockRestore());
+
+ it('declares every runtime workspace dependency exactly once', () => {
expect(workspaceDeps).not.toHaveLength(0);
+ expect(workspaceAliases.map(({pkg}) => pkg).sort()).toEqual(
+ [...workspaceDeps].sort(),
+ );
});
- it.each(workspaceDeps)('aliases %s to source', dep => {
- // Each workspace dependency must appear as a bare alias key in Vite's
- // `resolve.alias` so dev-mode resolution never falls back to the export
- // map's dist/ entry point, which is missing until the package is built.
- expect(viteAliasBlock).toContain(`'${dep}':`);
+ it.each(workspaceDeps)(
+ 'resolves %s through the intended source entries',
+ dep => {
+ const packageName = dep.slice('@astryxdesign/'.length);
+ const isTheme = packageName.startsWith('theme-');
+ const packageDir = isTheme
+ ? `themes/${packageName.slice('theme-'.length)}`
+ : packageName;
+ const source = path.join(rootDir, 'packages', packageDir, 'src');
+
+ expect(viteAliases[dep]).toBe(
+ isTheme ? path.join(source, 'source.ts') : source,
+ );
+ expect(existsSync(viteAliases[dep])).toBe(true);
+
+ if (packageName === 'vega') {
+ expect(stylexAliases).not.toHaveProperty(dep);
+ expect(stylexAliases).not.toHaveProperty(`${dep}/*`);
+ } else {
+ expect(stylexAliases[`${dep}/*`]).toEqual([path.join(source, '*')]);
+ if (isTheme) {
+ expect(stylexAliases).not.toHaveProperty(dep);
+ } else {
+ expect(stylexAliases[dep]).toEqual([source]);
+ }
+ }
+ },
+ );
+
+ it('preserves other Vite aliases while overriding workspace build entries', async () => {
+ const viteConfig = await config.viteFinal!(
+ {
+ resolve: {
+ alias: {
+ 'storybook-fixture': '/fixture.ts',
+ '@astryxdesign/core': '/packages/core/dist',
+ },
+ },
+ },
+ storybookOptions,
+ );
+
+ expect(viteConfig.resolve!.alias).toMatchObject({
+ 'storybook-fixture': '/fixture.ts',
+ '@astryxdesign/core': path.join(rootDir, 'packages/core/src'),
+ });
});
});
diff --git a/apps/storybook/.storybook/main.ts b/apps/storybook/.storybook/main.ts
index 9bad56c5ec..bb95c7bae1 100644
--- a/apps/storybook/.storybook/main.ts
+++ b/apps/storybook/.storybook/main.ts
@@ -1,5 +1,11 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/**
+ * @input Workspace source entries, Storybook's Vite config, Astryx StyleX plugin.
+ * @output Storybook config with Vite and StyleX aliases from one package table.
+ * @position Storybook configuration; keeps workspace packages usable unbuilt.
+ */
+
import type {StorybookConfig} from '@storybook/react-vite';
// Source, not the `@astryxdesign/build/vite` export: Storybook evaluates this
// file with Node's ESM resolver before any alias below it applies, and that
@@ -14,6 +20,105 @@ import {fileURLToPath} from 'node:url';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const rootDir = path.resolve(__dirname, '../../..');
+interface WorkspaceAlias {
+ pkg: string;
+ src: string;
+ stylex: 'both' | 'wildcard' | 'none';
+ vite?: string;
+}
+
+// Every runtime workspace dependency belongs here. Themes expose authored
+// source.ts to Vite, while StyleX only needs their token-module subpaths.
+export const workspaceAliases: WorkspaceAlias[] = [
+ {
+ pkg: '@astryxdesign/core',
+ src: 'packages/core/src',
+ stylex: 'both',
+ },
+ {
+ pkg: '@astryxdesign/lab',
+ src: 'packages/lab/src',
+ stylex: 'both',
+ },
+ {
+ pkg: '@astryxdesign/charts',
+ src: 'packages/charts/src',
+ stylex: 'both',
+ },
+ {
+ pkg: '@astryxdesign/richtext',
+ src: 'packages/richtext/src',
+ stylex: 'both',
+ },
+ {
+ pkg: '@astryxdesign/theme-butter',
+ src: 'packages/themes/butter/src',
+ stylex: 'wildcard',
+ vite: 'packages/themes/butter/src/source.ts',
+ },
+ {
+ pkg: '@astryxdesign/theme-chocolate',
+ src: 'packages/themes/chocolate/src',
+ stylex: 'wildcard',
+ vite: 'packages/themes/chocolate/src/source.ts',
+ },
+ {
+ pkg: '@astryxdesign/theme-gothic',
+ src: 'packages/themes/gothic/src',
+ stylex: 'wildcard',
+ vite: 'packages/themes/gothic/src/source.ts',
+ },
+ {
+ pkg: '@astryxdesign/theme-matcha',
+ src: 'packages/themes/matcha/src',
+ stylex: 'wildcard',
+ vite: 'packages/themes/matcha/src/source.ts',
+ },
+ {
+ pkg: '@astryxdesign/theme-neutral',
+ src: 'packages/themes/neutral/src',
+ stylex: 'wildcard',
+ vite: 'packages/themes/neutral/src/source.ts',
+ },
+ {
+ pkg: '@astryxdesign/theme-probe',
+ src: 'packages/themes/probe/src',
+ stylex: 'wildcard',
+ vite: 'packages/themes/probe/src/source.ts',
+ },
+ {
+ pkg: '@astryxdesign/theme-stone',
+ src: 'packages/themes/stone/src',
+ stylex: 'wildcard',
+ vite: 'packages/themes/stone/src/source.ts',
+ },
+ {
+ pkg: '@astryxdesign/theme-y2k',
+ src: 'packages/themes/y2k/src',
+ stylex: 'wildcard',
+ vite: 'packages/themes/y2k/src/source.ts',
+ },
+ {
+ pkg: '@astryxdesign/vega',
+ src: 'packages/vega/src',
+ // Vega has no StyleX imports.
+ stylex: 'none',
+ },
+];
+
+const stylexAliases: Record<string, string[]> = {};
+const viteAliases: Record<string, string> = {};
+for (const {pkg, src, stylex, vite} of workspaceAliases) {
+ const source = path.resolve(rootDir, src);
+ viteAliases[pkg] = vite ? path.resolve(rootDir, vite) : source;
+ if (stylex !== 'none') {
+ stylexAliases[`${pkg}/*`] = [path.join(source, '*')];
+ }
+ if (stylex === 'both') {
+ stylexAliases[pkg] = [source];
+ }
+}
+
const lightningcssTargets = {
chrome: 123 << 16,
firefox: 120 << 16,
@@ -85,50 +190,7 @@ const config: StorybookConfig = {
stylexOptions: {
dev: false,
styleResolution: 'application-order',
- aliases: {
- '@astryxdesign/core/*': [
- path.join(rootDir, 'packages/core/src/*'),
- ],
- '@astryxdesign/core': [path.join(rootDir, 'packages/core/src')],
- '@astryxdesign/lab/*': [path.join(rootDir, 'packages/lab/src/*')],
- '@astryxdesign/lab': [path.join(rootDir, 'packages/lab/src')],
- '@astryxdesign/charts/*': [
- path.join(rootDir, 'packages/charts/src/*'),
- ],
- '@astryxdesign/charts': [
- path.join(rootDir, 'packages/charts/src'),
- ],
- '@astryxdesign/richtext/*': [
- path.join(rootDir, 'packages/richtext/src/*'),
- ],
- '@astryxdesign/richtext': [
- path.join(rootDir, 'packages/richtext/src'),
- ],
- '@astryxdesign/theme-butter/*': [
- path.join(rootDir, 'packages/themes/butter/src/*'),
- ],
- '@astryxdesign/theme-chocolate/*': [
- path.join(rootDir, 'packages/themes/chocolate/src/*'),
- ],
- '@astryxdesign/theme-gothic/*': [
- path.join(rootDir, 'packages/themes/gothic/src/*'),
- ],
- '@astryxdesign/theme-matcha/*': [
- path.join(rootDir, 'packages/themes/matcha/src/*'),
- ],
- '@astryxdesign/theme-neutral/*': [
- path.join(rootDir, 'packages/themes/neutral/src/*'),
- ],
- '@astryxdesign/theme-probe/*': [
- path.join(rootDir, 'packages/themes/probe/src/*'),
- ],
- '@astryxdesign/theme-stone/*': [
- path.join(rootDir, 'packages/themes/stone/src/*'),
- ],
- '@astryxdesign/theme-y2k/*': [
- path.join(rootDir, 'packages/themes/y2k/src/*'),
- ],
- },
+ aliases: stylexAliases,
unstable_moduleResolution: {
type: 'commonJS',
rootDir: rootDir,
@@ -144,46 +206,7 @@ const config: StorybookConfig = {
...config.resolve,
alias: {
...config.resolve?.alias,
- '@astryxdesign/core': path.resolve(rootDir, 'packages/core/src'),
- '@astryxdesign/lab': path.resolve(rootDir, 'packages/lab/src'),
- '@astryxdesign/charts': path.resolve(rootDir, 'packages/charts/src'),
- '@astryxdesign/richtext': path.resolve(
- rootDir,
- 'packages/richtext/src',
- ),
- '@astryxdesign/theme-butter': path.resolve(
- rootDir,
- 'packages/themes/butter/src/source.ts',
- ),
- '@astryxdesign/theme-chocolate': path.resolve(
- rootDir,
- 'packages/themes/chocolate/src/source.ts',
- ),
- '@astryxdesign/theme-gothic': path.resolve(
- rootDir,
- 'packages/themes/gothic/src/source.ts',
- ),
- '@astryxdesign/theme-matcha': path.resolve(
- rootDir,
- 'packages/themes/matcha/src/source.ts',
- ),
- '@astryxdesign/theme-neutral': path.resolve(
- rootDir,
- 'packages/themes/neutral/src/source.ts',
- ),
- '@astryxdesign/theme-probe': path.resolve(
- rootDir,
- 'packages/themes/probe/src/source.ts',
- ),
- '@astryxdesign/theme-stone': path.resolve(
- rootDir,
- 'packages/themes/stone/src/source.ts',
- ),
- '@astryxdesign/theme-y2k': path.resolve(
- rootDir,
- 'packages/themes/y2k/src/source.ts',
- ),
- '@astryxdesign/vega': path.resolve(rootDir, 'packages/vega/src'),
+ ...viteAliases,
},
},
css: {
diff --git a/apps/storybook/README.md b/apps/storybook/README.md
index cb8f88784f..aafeaeb0cd 100644
--- a/apps/storybook/README.md
+++ b/apps/storybook/README.md
@@ -52,10 +52,11 @@ export const ThemeSheet: Story = {
};
```
-| File | Role | Purpose |
-| -------------------------------- | ------------- | ------------------------------------------------------------- |
-| `.storybook/main.ts` | Config | Storybook Vite integration, preview build target, and aliases |
-| `LOCAL_STARTUP_INVESTIGATION.md` | Investigation | Why local Storybook previews can appear before they are ready |
-| `package.json` | Config | Package dependencies and scripts |
-| `tsconfig.json` | Config | TypeScript compiler configuration |
-| `vite.config.ts` | Config | Vite bundler configuration with path aliases |
+| File | Role | Purpose |
+| -------------------------------- | ------------- | ---------------------------------------------------------------------------------- |
+| `.storybook/main.ts` | Config | Storybook Vite integration, preview build target, and shared workspace alias table |
+| `.storybook/main.test.ts` | Tests | Source alias coverage and cold-clone config loading |
+| `LOCAL_STARTUP_INVESTIGATION.md` | Investigation | Why local Storybook previews can appear before they are ready |
+| `package.json` | Config | Package dependencies and scripts |
+| `tsconfig.json` | Config | TypeScript compiler configuration |
+| `vite.config.ts` | Config | Vite bundler configuration with path aliases |