@astryxdesign/build 0.0.0-bootstrap.0 → 0.0.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meta Platforms, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,247 @@
 # @astryxdesign/build
 
-This is a `0.0.0-bootstrap.0` placeholder published only to claim the npm name while configuring npm trusted publishing. Do not install it; it will be superseded by the first real release.
+Build plugins for XDS source builds. Provides babel, PostCSS, and Vite integrations that compile XDS library and product code with separate class name prefixes, which enables independent CSS layers:
+
+```
+reset < astryx-base (library, astryx prefix) < astryx-theme < product (app, x prefix)
+```
+
+## Why?
+
+StyleX generates atomic CSS: same declaration = same class name. Without separate prefixes, library and product classes collide and can't be placed in independent CSS layers, which breaks theme overrides.
+
+`@astryxdesign/build` solves this by:
+
+1. Compiling XDS library code with `astryx` prefix (`.astryx78zum5`)
+2. Compiling product code with default `x` prefix (`.x78zum5`)
+3. Placing each group in its own CSS `@layer`
+
+## Packages
+
+| Export               | Purpose                                       | Platform                    |
+| -------------------- | --------------------------------------------- | --------------------------- |
+| `@astryxdesign/build/babel`   | Babel plugin: splits class prefixes per file  | Next.js, any babel pipeline |
+| `@astryxdesign/build/postcss` | PostCSS plugin: compiles + splits CSS layers  | Next.js                     |
+| `@astryxdesign/build/vite`    | Vite plugin: wraps unplugin + splits layers   | Vite, Storybook             |
+
+## Install
+
+```bash
+npm install -D @astryxdesign/build @stylexjs/babel-plugin @babel/core
+```
+
+For Vite, also install:
+
+```bash
+npm install -D @stylexjs/unplugin
+```
+
+---
+
+## Next.js Setup
+
+### 1. babel.config.js
+
+```js
+const path = require('path');
+
+module.exports = {
+  presets: ['next/babel'],
+  plugins: [
+    [
+      '@astryxdesign/build/babel',
+      {
+        dev: process.env.NODE_ENV !== 'production',
+        runtimeInjection: false,
+        treeshakeCompensation: true,
+        enableInlinedConditionalMerge: true,
+        aliases: {
+          '@astryxdesign/core/*': [path.join(__dirname, 'node_modules/@astryxdesign/core/*')],
+          '@astryxdesign/core': [path.join(__dirname, 'node_modules/@astryxdesign/core')],
+        },
+        unstable_moduleResolution: {type: 'commonJS'},
+      },
+    ],
+  ],
+};
+```
+
+### 2. postcss.config.js
+
+```js
+const path = require('path');
+
+module.exports = {
+  plugins: {
+    '@astryxdesign/build/postcss': {
+      appDir: 'src',
+      babelPlugins: [
+        [
+          '@stylexjs/babel-plugin',
+          {
+            dev: process.env.NODE_ENV !== 'production',
+            runtimeInjection: false,
+            treeshakeCompensation: true,
+            enableInlinedConditionalMerge: true,
+            aliases: {
+              '@astryxdesign/core/*': [path.join(__dirname, 'node_modules/@astryxdesign/core/*')],
+              '@astryxdesign/core': [path.join(__dirname, 'node_modules/@astryxdesign/core')],
+            },
+            unstable_moduleResolution: {type: 'commonJS'},
+          },
+        ],
+      ],
+    },
+  },
+};
+```
+
+### 3. next.config.mjs
+
+```js
+const nextConfig = {
+  transpilePackages: ['@astryxdesign/core', '@astryxdesign/theme-default'],
+  webpack: config => {
+    // Resolve to source TypeScript instead of dist
+    config.resolve.conditionNames = ['source', 'import', 'require', 'default'];
+    return config;
+  },
+};
+
+export default nextConfig;
+```
+
+### 4. CSS files
+
+`src/app/layers.css`:
+
+```css
+@layer reset, astryx-base, astryx-theme, product;
+```
+
+`src/app/globals.css`:
+
+```css
+@import './layers.css';
+@import '@astryxdesign/core/reset.css';
+@import '@astryxdesign/theme-default/theme.css';
+
+@stylex;
+```
+
+> `layers.css` must be a separate file because webpack hoists `@import` content above inline CSS.
+
+### 5. Browserslist
+
+```json
+{
+  "browserslist": ["last 1 Chrome version"]
+}
+```
+
+---
+
+## Vite Setup
+
+```ts
+import {xdsStylex} from '@astryxdesign/build/vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [
+    ...xdsStylex({
+      stylexOptions: {
+        dev: process.env.NODE_ENV === 'development',
+        runtimeInjection: false,
+        treeshakeCompensation: true,
+        unstable_moduleResolution: {
+          type: 'commonJS',
+          rootDir: __dirname,
+        },
+      },
+    }),
+    react(),
+  ],
+  resolve: {
+    alias: {
+      '@astryxdesign/core': path.resolve(__dirname, 'node_modules/@astryxdesign/core/src'),
+    },
+  },
+  optimizeDeps: {
+    exclude: ['@astryxdesign/core', '@astryxdesign/theme-default'],
+  },
+});
+```
+
+---
+
+## How it works
+
+### Babel plugin (`@astryxdesign/build/babel`)
+
+Wraps `@stylexjs/babel-plugin` with two internal instances: one with `classNamePrefix: 'astryx'` for library files, one with default `'x'` for product files. Routes each file to the correct instance based on its path.
+
+Library patterns (configurable):
+
+- `packages/core/`
+- `packages/themes/`
+- `node_modules/@astryxdesign/`
+
+### PostCSS plugin (`@astryxdesign/build/postcss`)
+
+Compiles StyleX from both library and product source files in two separate passes with different prefixes. Wraps the results in named `@layer` blocks:
+
+- Library rules → `@layer astryx-base`
+- Product rules → `@layer product`
+
+### Vite plugin (`@astryxdesign/build/vite`)
+
+Wraps `@stylexjs/unplugin` and intercepts the dev CSS endpoint (`/virtual:stylex.css`). Partitions the collected rules by file path and serves split-layer CSS.
+
+---
+
+## Advanced Options
+
+### Babel plugin
+
+```js
+[
+  '@astryxdesign/build/babel',
+  {
+    // Patterns to identify library files (default shown)
+    libraryPatterns: [
+      'packages/core/',
+      'packages/themes/',
+      'node_modules/@astryxdesign/',
+    ],
+
+    // Class name prefix for library styles (default: 'astryx')
+    libraryPrefix: 'astryx',
+
+    // Class name prefix for product styles (default: 'x')
+    classNamePrefix: 'x',
+
+    // ... all @stylexjs/babel-plugin options
+  },
+];
+```
+
+### PostCSS plugin
+
+```js
+'@astryxdesign/build/postcss': {
+  appDir: 'src',           // Your app source directory
+  babelPlugins: [...],     // StyleX babel plugin config
+  libraryPrefix: 'astryx',   // Prefix for library CSS (default: 'astryx')
+  extraInclude: [...],     // Additional glob patterns
+  layers: {                // Layer names (defaults shown)
+    library: 'astryx-base',
+    product: 'product',
+  },
+}
+```
+
+## Related
+
+- [example-nextjs-source](../../apps/example-nextjs-source/): full Next.js source build example
+- [`@stylexjs/babel-plugin`](https://github.com/facebook/stylex): the underlying StyleX compiler

package/dist/vite.mjs

@@ -0,0 +1,284 @@
+// Built from src/vite.ts — do not edit directly
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/vite.ts
+import stylexBabelPlugin from "@stylexjs/babel-plugin";
+import stylex from "@stylexjs/unplugin";
+import path from "path";
+import { fileURLToPath } from "url";
+var __dirname = path.dirname(fileURLToPath(import.meta.url));
+var LIBRARY_PATTERN = "node_modules/@astryxdesign/";
+var STYLEX_CSS_PATH = "/virtual:stylex.css";
+var LIGHTNINGCSS_TARGETS = {
+  chrome: 123 << 16,
+  firefox: 120 << 16,
+  safari: 17 << 16 | 5 << 8
+};
+function xdsStylex(options = {}) {
+  if ("stylexOptions" in options && options.stylexOptions) {
+    return xdsStylexLegacy(options);
+  }
+  const opts = options;
+  const {
+    dev = process.env.NODE_ENV !== "production",
+    rootDir = process.cwd(),
+    libraryPattern = LIBRARY_PATTERN,
+    layers = {},
+    lightningcssTargets,
+    stylexPrefix = "astryx",
+    stylexOverrides = {}
+  } = opts;
+  const libraryLayer = layers.library ?? "astryx-base";
+  const productLayer = layers.product ?? "product";
+  const stylexOptions = {
+    dev,
+    runtimeInjection: false,
+    treeshakeCompensation: true,
+    unstable_moduleResolution: {
+      type: "commonJS",
+      rootDir
+    },
+    ...lightningcssTargets && {
+      lightningcssOptions: { targets: lightningcssTargets }
+    },
+    ...stylexOverrides
+  };
+  const xdsBabelPlugin = path.resolve(__dirname, "../src/babel.js");
+  const basePlugin = stylex.vite({
+    ...stylexOptions,
+    useCSSLayers: true,
+    babelConfig: {
+      plugins: [
+        [
+          xdsBabelPlugin,
+          {
+            ...stylexOptions,
+            libraryPrefix: stylexPrefix,
+            babelConfig: void 0
+          }
+        ]
+      ]
+    }
+  });
+  const layerOrderPlugin = {
+    name: "xds-css-layer-order",
+    transformIndexHtml() {
+      return [
+        {
+          tag: "style",
+          children: `@layer reset, ${libraryLayer}, astryx-theme, ${productLayer};`,
+          injectTo: "head-prepend"
+        }
+      ];
+    }
+  };
+  const configPlugin = {
+    name: "xds-config",
+    config() {
+      let xdsPackages = ["@astryxdesign/core"];
+      try {
+        const fs = __require("fs");
+        const xdsDir = path.resolve(rootDir, "node_modules/@astryxdesign");
+        if (fs.existsSync(xdsDir)) {
+          xdsPackages = fs.readdirSync(xdsDir).filter((name) => !name.startsWith(".")).map((name) => `@astryxdesign/${name}`);
+        }
+      } catch {
+      }
+      return {
+        resolve: {
+          alias: {
+            "@astryxdesign/core/theme/tokens.stylex": path.resolve(
+              rootDir,
+              "node_modules/@astryxdesign/core/src/theme/tokens.stylex.ts"
+            ),
+            "@astryxdesign/core": path.resolve(rootDir, "node_modules/@astryxdesign/core/src")
+          }
+        },
+        optimizeDeps: {
+          exclude: xdsPackages
+        }
+      };
+    }
+  };
+  const splitLayerPlugin = {
+    name: "xds-split-layers",
+    configureServer(server) {
+      let stylexPlugin = null;
+      return () => {
+        for (const p of server.config.plugins.flat()) {
+          if (p?.__stylexGetSharedStore) {
+            stylexPlugin = p;
+            break;
+          }
+        }
+        server.middlewares.stack.unshift({
+          route: "",
+          handle: (req, res, next) => {
+            if (!req.url?.startsWith(STYLEX_CSS_PATH)) {
+              return next();
+            }
+            if (!stylexPlugin) {
+              res.statusCode = 200;
+              res.setHeader("Content-Type", "text/css");
+              res.end("");
+              return;
+            }
+            const shared = stylexPlugin.__stylexGetSharedStore?.();
+            const rulesById = shared?.rulesById;
+            if (!rulesById || rulesById.size === 0) {
+              res.statusCode = 200;
+              res.setHeader("Content-Type", "text/css");
+              res.end("");
+              return;
+            }
+            const libraryRules = [];
+            const productRules = [];
+            for (const [filePath, rules] of rulesById.entries()) {
+              if (filePath.includes(libraryPattern)) {
+                libraryRules.push(...rules);
+              } else {
+                productRules.push(...rules);
+              }
+            }
+            const libraryCss = libraryRules.length ? stylexBabelPlugin.processStylexRules(libraryRules, {
+              useLayers: true
+            }) : "";
+            const productCss = productRules.length ? stylexBabelPlugin.processStylexRules(productRules, {
+              useLayers: true
+            }) : "";
+            const parts = [];
+            if (libraryCss)
+              parts.push(`@layer ${libraryLayer} {
+${libraryCss}
+}`);
+            if (productCss)
+              parts.push(`@layer ${productLayer} {
+${productCss}
+}`);
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "text/css");
+            res.setHeader("Cache-Control", "no-store");
+            res.end(parts.join("\n\n"));
+          }
+        });
+      };
+    }
+  };
+  return [configPlugin, layerOrderPlugin, basePlugin, splitLayerPlugin];
+}
+function xdsStylexLegacy(options) {
+  const {
+    stylexOptions,
+    libraryPattern = LIBRARY_PATTERN,
+    stylexPrefix = "astryx",
+    layers = {}
+  } = options;
+  const libraryLayer = layers.library ?? "astryx-base";
+  const productLayer = layers.product ?? "product";
+  const xdsBabelPlugin = path.resolve(__dirname, "../src/babel.js");
+  const existingPlugins = stylexOptions.babelConfig?.plugins ?? [];
+  const basePlugin = stylex.vite({
+    ...stylexOptions,
+    useCSSLayers: true,
+    babelConfig: {
+      ...stylexOptions.babelConfig,
+      plugins: [
+        [
+          xdsBabelPlugin,
+          {
+            ...stylexOptions,
+            libraryPrefix: stylexPrefix,
+            babelConfig: void 0
+          }
+        ],
+        ...existingPlugins
+      ]
+    }
+  });
+  const layerOrderPlugin = {
+    name: "xds-css-layer-order",
+    transformIndexHtml() {
+      return [
+        {
+          tag: "style",
+          children: `@layer reset, ${libraryLayer}, astryx-theme, ${productLayer};`,
+          injectTo: "head-prepend"
+        }
+      ];
+    }
+  };
+  const splitLayerPlugin = {
+    name: "xds-split-layers",
+    configureServer(server) {
+      let stylexPlugin = null;
+      return () => {
+        for (const p of server.config.plugins.flat()) {
+          if (p?.__stylexGetSharedStore) {
+            stylexPlugin = p;
+            break;
+          }
+        }
+        server.middlewares.stack.unshift({
+          route: "",
+          handle: (req, res, next) => {
+            if (!req.url?.startsWith(STYLEX_CSS_PATH)) {
+              return next();
+            }
+            if (!stylexPlugin) {
+              res.statusCode = 200;
+              res.setHeader("Content-Type", "text/css");
+              res.end("");
+              return;
+            }
+            const shared = stylexPlugin.__stylexGetSharedStore?.();
+            const rulesById = shared?.rulesById;
+            if (!rulesById || rulesById.size === 0) {
+              res.statusCode = 200;
+              res.setHeader("Content-Type", "text/css");
+              res.end("");
+              return;
+            }
+            const libraryRules = [];
+            const productRules = [];
+            for (const [filePath, rules] of rulesById.entries()) {
+              if (filePath.includes(libraryPattern)) {
+                libraryRules.push(...rules);
+              } else {
+                productRules.push(...rules);
+              }
+            }
+            const libraryCss = libraryRules.length ? stylexBabelPlugin.processStylexRules(libraryRules, {
+              useLayers: true
+            }) : "";
+            const productCss = productRules.length ? stylexBabelPlugin.processStylexRules(productRules, {
+              useLayers: true
+            }) : "";
+            const parts = [];
+            if (libraryCss)
+              parts.push(`@layer ${libraryLayer} {
+${libraryCss}
+}`);
+            if (productCss)
+              parts.push(`@layer ${productLayer} {
+${productCss}
+}`);
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "text/css");
+            res.setHeader("Cache-Control", "no-store");
+            res.end(parts.join("\n\n"));
+          }
+        });
+      };
+    }
+  };
+  return [layerOrderPlugin, basePlugin, splitLayerPlugin];
+}
+export {
+  LIGHTNINGCSS_TARGETS,
+  xdsStylex
+};

package/package.json

@@ -1,11 +1,60 @@
 {
   "name": "@astryxdesign/build",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder published to claim the npm name during trusted publishing setup. Do not install.",
-  "homepage": "https://github.com/facebook/astryx",
+  "version": "0.0.15",
+  "description": "Build plugins for XDS source builds — babel, PostCSS, and Vite integrations",
+  "author": "Meta Open Source",
   "license": "MIT",
+  "homepage": "https://github.com/facebook/astryx#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/facebook/astryx.git"
+    "url": "git+https://github.com/facebook/astryx.git",
+    "directory": "packages/build"
+  },
+  "bugs": {
+    "url": "https://github.com/facebook/astryx/issues"
+  },
+  "keywords": [
+    "xds",
+    "postcss",
+    "stylex",
+    "css-layers",
+    "design-system"
+  ],
+  "main": "./src/config.js",
+  "exports": {
+    ".": "./src/config.js",
+    "./babel": "./src/babel.js",
+    "./postcss": "./src/index.js",
+    "./vite": "./dist/vite.mjs",
+    "./next": "./src/next.js"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "peerDependencies": {
+    "@stylexjs/babel-plugin": ">=0.18.0",
+    "@babel/core": ">=7.0.0",
+    "@stylexjs/unplugin": ">=0.18.0",
+    "vite": ">=5.0.0"
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.0",
+    "glob-parent": "^6.0.0",
+    "is-glob": "^4.0.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.1"
+  },
+  "peerDependenciesMeta": {
+    "@stylexjs/unplugin": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "node build.mjs"
   }
-}
+}