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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/package.json b/package.jsonindex 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.mdindex 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.jsonindex 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.yamlindex fb426cdae1..63fc756cdf 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -53,6 +53,9 @@ importers:'@vitest/coverage-v8':specifier: ^2.1.0version: 2.1.9([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]))+ esbuild:+ specifier: '>=0.28.1'+ version: 0.28.1eslint:specifier: ^10.5.0version: 10.5.0([email protected])diff --git a/scripts/build-umd.mjs b/scripts/build-umd.mjsnew file mode 100644index 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.jsindex 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',