Skip to content

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

TypeScript

feat(core): add prebuilt UMD bundle for CDN/script-tag usage (#3167)

Cindy Zhangfde330128579
diff --git a/.changeset/cdn-umd-bundle.md b/.changeset/cdn-umd-bundle.md
new file mode 100644
index 0000000000..058b633762
--- /dev/null
+++ b/.changeset/cdn-umd-bundle.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Add a prebuilt UMD bundle (`dist/astryx.umd.js`, global `Astryx`) plus `unpkg`/`jsdelivr` fields, so the library works directly from a CDN via a `<script>` tag with no bundler. React/ReactDOM stay as peer globals; the StyleX runtime is bundled in.
+
+@cixzhang
diff --git a/package.json b/package.json
index 3200d8e1ea..83e25a06c6 100644
--- a/package.json
+++ b/package.json
@@ -45,6 +45,7 @@
"@types/react-dom": "^19.2.3",
"@vitejs/plugin-react": "^4.3.0",
"@vitest/coverage-v8": "^2.1.0",
+ "esbuild": "^0.28.1",
"eslint": "^10.5.0",
"eslint-plugin-react-compiler": "19.1.0-rc.2",
"husky": "^9.1.7",
diff --git a/packages/core/README.md b/packages/core/README.md
index 38869c8f95..5809bbd4de 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -183,3 +183,71 @@ npm install @astryxdesign/core @astryxdesign/theme-neutral
```
Same CSS imports and providers as above. No build plugins needed; XDS ships pre-built.
+
+### No build step (CDN)
+
+For prototypes, embeds, or pages without a bundler, load the components straight
+from a public CDN. Two delivery options ship in the published package:
+
+**1. UMD global (`<script>` tag).** A single pre-bundled file exposes every export
+on `window.Astryx`. React and ReactDOM are peer dependencies — load them yourself.
+Pair it with the precompiled stylesheet.
+
+```html
+<!doctype html>
+<html data-astryx-theme="neutral">
+ <head>
+ <link
+ rel="stylesheet"
+ href="https://cdn.jsdelivr.net/npm/@astryxdesign/core/src/reset.css" />
+ <link
+ rel="stylesheet"
+ href="https://cdn.jsdelivr.net/npm/@astryxdesign/core/dist/astryx.css" />
+ </head>
+ <body>
+ <div id="root"></div>
+ <script
+ crossorigin
+ src="https://unpkg.com/react@19/umd/react.production.min.js"></script>
+ <script
+ crossorigin
+ src="https://unpkg.com/react-dom@19/umd/react-dom.production.min.js"></script>
+ <script src="https://cdn.jsdelivr.net/npm/@astryxdesign/core/dist/astryx.umd.js"></script>
+ <script>
+ const {Button, Card} = window.Astryx;
+ const e = React.createElement;
+ ReactDOM.createRoot(document.getElementById('root')).render(
+ e(Card, null, e(Button, {variant: 'primary'}, 'Hello from a CDN')),
+ );
+ </script>
+ </body>
+</html>
+```
+
+**2. ES modules (no UMD, no globals).** Use [esm.sh](https://esm.sh), which rewrites
+bare imports to browser-resolvable URLs. An import map keeps a single React instance.
+
+```html
+<link
+ rel="stylesheet"
+ href="https://cdn.jsdelivr.net/npm/@astryxdesign/core/dist/astryx.css" />
+<script type="importmap">
+ {
+ "imports": {
+ "react": "https://esm.sh/react@19",
+ "react-dom/client": "https://esm.sh/react-dom@19/client",
+ "@astryxdesign/core": "https://esm.sh/@astryxdesign/core?external=react,react-dom"
+ }
+ }
+</script>
+<script type="module">
+ import {createRoot} from 'react-dom/client';
+ import {Button} from '@astryxdesign/core';
+ // ...render as usual
+</script>
+```
+
+> Pin a version in production (e.g. `@astryxdesign/[email protected]`) — unversioned CDN URLs
+> resolve to the latest release and are cached aggressively. The raw ESM entry
+> (`dist/index.js`) uses bare `react` imports and will **not** run from a plain
+> `<script src>`; use the UMD global or esm.sh as shown above.
diff --git a/packages/core/package.json b/packages/core/package.json
index b321f394f7..8dfc6542a3 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -27,6 +27,8 @@
"type": "module",
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
+ "unpkg": "./dist/astryx.umd.js",
+ "jsdelivr": "./dist/astryx.umd.js",
"sideEffects": [
"**/*.stylex.ts",
"**/*.stylex.js",
@@ -47,6 +49,7 @@
"types": "./src/astryx.css.d.ts",
"default": "./dist/astryx.css"
},
+ "./astryx.umd.js": "./dist/astryx.umd.js",
"./tailwind-theme.css": {
"types": "./src/tailwind-theme.css.d.ts",
"default": "./src/tailwind-theme.css"
@@ -619,9 +622,10 @@
],
"scripts": {
"prepack": "pnpm build",
- "build": "rm -rf dist && pnpm build:esm && tsc --project tsconfig.build.json && pnpm build:css",
+ "build": "rm -rf dist && pnpm build:esm && tsc --project tsconfig.build.json && pnpm build:css && pnpm build:umd",
"build:esm": "babel src --out-dir dist --extensions '.ts,.tsx' --out-file-extension '.js' --ignore '**/*.test.ts,**/*.test.tsx,**/__tests__/**,**/*.perf.test.*,**/*.doc.mjs,**/*.d.ts,**/*.css,**/*.css.d.ts' --config-file ./babel.config.json",
"build:css": "node ../../scripts/build-css.mjs",
+ "build:umd": "node ../../scripts/build-umd.mjs",
"dev": "babel src --watch --out-dir dist --extensions '.ts,.tsx' --out-file-extension '.js' --ignore '**/*.test.*,**/*.doc.mjs,**/*.d.ts,**/*.css*' --config-file ./babel.config.json",
"test": "vitest run --root ../..",
"test:watch": "vitest --root ../..",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index fb426cdae1..63fc756cdf 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -53,6 +53,9 @@ importers:
'@vitest/coverage-v8':
specifier: ^2.1.0
+ esbuild:
+ specifier: '>=0.28.1'
+ version: 0.28.1
eslint:
specifier: ^10.5.0
version: 10.5.0([email protected])
diff --git a/scripts/build-umd.mjs b/scripts/build-umd.mjs
new file mode 100644
index 0000000000..d9dc1b0208
--- /dev/null
+++ b/scripts/build-umd.mjs
@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file build-umd.mjs
+ * Post-build script that bundles the compiled ESM (dist/index.js) into a single
+ * browser-global IIFE file for direct <script> / CDN usage.
+ *
+ * Usage: node scripts/build-umd.mjs (runs after build:esm + build:css)
+ *
+ * Output:
+ * packages/core/dist/astryx.umd.js global: window.Astryx
+ * packages/core/dist/astryx.umd.js.map
+ *
+ * react / react-dom are EXTERNAL, resolved to the browser globals React /
+ * ReactDOM (matching peerDependencies) — consumers load React via their own
+ * <script> tags. The StyleX runtime (@stylexjs/stylex) IS bundled in, since
+ * components call stylex.props() at runtime and CDN users should not need a
+ * second global.
+ *
+ * Drop-in usage (pair with the precompiled stylesheet):
+ * <link rel="stylesheet" href=".../@astryxdesign/core/dist/astryx.css" />
+ * <script crossorigin src="https://unpkg.com/react@19/umd/react.production.min.js"></script>
+ * <script crossorigin src="https://unpkg.com/react-dom@19/umd/react-dom.production.min.js"></script>
+ * <script src=".../@astryxdesign/core/dist/astryx.umd.js"></script>
+ * <script>const { Button } = window.Astryx; ...</script>
+ */
+
+import {build} from 'esbuild';
+import path from 'path';
+import {fileURLToPath} from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CORE = path.resolve(__dirname, '..', 'packages/core');
+const ENTRY = path.resolve(CORE, 'dist/index.js');
+const OUTFILE = path.resolve(CORE, 'dist/astryx.umd.js');
+
+// React 19 public named exports that compiled component code may import.
+// Anything not listed falls back to a property lookup on the global at runtime.
+const REACT_NAMED = [
+ 'Children', 'Component', 'Fragment', 'Profiler', 'PureComponent',
+ 'StrictMode', 'Suspense', 'cloneElement', 'createContext', 'createElement',
+ 'createRef', 'forwardRef', 'isValidElement', 'lazy', 'memo', 'startTransition',
+ 'use', 'useActionState', 'useCallback', 'useContext', 'useDebugValue',
+ 'useDeferredValue', 'useEffect', 'useId', 'useImperativeHandle',
+ 'useInsertionEffect', 'useLayoutEffect', 'useMemo', 'useOptimistic',
+ 'useReducer', 'useRef', 'useState', 'useSyncExternalStore', 'useTransition',
+ 'version',
+];
+
+const REACT_DOM_NAMED = [
+ 'createPortal', 'flushSync', 'preconnect', 'prefetchDNS', 'preinit',
+ 'preinitModule', 'preload', 'preloadModule', 'requestFormReset', 'version',
+];
+
+function reactGlobalsPlugin() {
+ const filter = /^(react|react-dom|react-dom\/client|react\/jsx-runtime)$/;
+ return {
+ name: 'react-globals',
+ setup(b) {
+ b.onResolve({filter}, args => ({path: args.path, namespace: 'rg'}));
+ b.onLoad({filter: /.*/, namespace: 'rg'}, args => {
+ if (args.path === 'react') {
+ return {loader: 'js', contents: namedReexport('React', REACT_NAMED)};
+ }
+ if (args.path === 'react-dom') {
+ return {
+ loader: 'js',
+ contents:
+ namedReexport('ReactDOM', REACT_DOM_NAMED) +
+ `\nexport const render = R.render;\nexport const unmountComponentAtNode = R.unmountComponentAtNode;`,
+ };
+ }
+ if (args.path === 'react-dom/client') {
+ return {
+ loader: 'js',
+ contents: `const R = globalThis.ReactDOM;
+export const createRoot = R.createRoot;
+export const hydrateRoot = R.hydrateRoot;
+export default R;`,
+ };
+ }
+ // react/jsx-runtime — map to React.jsx / jsxs / Fragment with a
+ // createElement fallback for React builds that omit the runtime helpers.
+ return {
+ loader: 'js',
+ contents: `const R = globalThis.React;
+const _h = (type, props, key) => {
+ const p = props || {};
+ const {children, ...rest} = p;
+ if (key !== undefined) rest.key = key;
+ const kids = children === undefined ? [] : (Array.isArray(children) ? children : [children]);
+ return R.createElement(type, rest, ...kids);
+};
+export const jsx = R.jsx || _h;
+export const jsxs = R.jsxs || _h;
+export const Fragment = R.Fragment;
+export default R;`,
+ };
+ });
+ },
+ };
+}
+
+function namedReexport(globalName, names) {
+ const lines = names.map(n => `export const ${n} = R.${n};`).join('\n');
+ return `const R = globalThis.${globalName};\n${lines}\nexport default R;`;
+}
+
+await build({
+ entryPoints: [ENTRY],
+ outfile: OUTFILE,
+ bundle: true,
+ format: 'iife',
+ globalName: 'Astryx',
+ platform: 'browser',
+ target: ['es2020'],
+ minify: true,
+ sourcemap: true,
+ legalComments: 'none',
+ banner: {
+ js: '/* @astryxdesign/core UMD bundle — requires global React & ReactDOM (see dist/astryx.umd.js header). */',
+ },
+ plugins: [reactGlobalsPlugin()],
+});
+
+console.log('Built dist/astryx.umd.js (global: Astryx)');
diff --git a/scripts/sync-exports.js b/scripts/sync-exports.js
index 1233e19f54..4d984d4e3f 100644
--- a/scripts/sync-exports.js
+++ b/scripts/sync-exports.js
@@ -58,6 +58,7 @@ const STATIC_EXPORTS = {
types: './src/astryx.css.d.ts',
default: './dist/astryx.css',
},
+ './astryx.umd.js': './dist/astryx.umd.js',
'./tailwind-theme.css': {
types: './src/tailwind-theme.css.d.ts',
default: './src/tailwind-theme.css',