Skip to content

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

TypeScript

feat(examples): add XDSLinkProvider + convert example-nextjs to dist (#1413)

Cindy Zhang2d5c44b9f953
diff --git a/apps/example-nextjs-stylex/.gitignore b/apps/example-nextjs-stylex/.gitignore
new file mode 100644
index 0000000000..a680367ef5
--- /dev/null
+++ b/apps/example-nextjs-stylex/.gitignore
@@ -0,0 +1 @@
+.next
diff --git a/apps/example-nextjs-stylex/README.md b/apps/example-nextjs-stylex/README.md
new file mode 100644
index 0000000000..cd700977af
--- /dev/null
+++ b/apps/example-nextjs-stylex/README.md
@@ -0,0 +1,134 @@
+# XDS Example — Next.js + StyleX (Dist)
+
+Reference application for consuming **@xds/core** as a pre-built dist package with **StyleX** for product-level styles.
+
+XDS component CSS comes pre-built — no need to compile XDS source. StyleX is only used for your own app-level layout and custom styles, compiled at build time via the PostCSS plugin.
+
+## CSS Layer Integration
+
+This example uses StyleX's `useCSSLayers.before` option to declare XDS dist layers before the StyleX app layers:
+
+```js
+// postcss.config.js
+useCSSLayers: {
+ before: ['reset', 'xds-base', 'xds-theme'],
+}
+```
+
+This produces a layer order of:
+
+```
+reset < xds-base < xds-theme < stylex.base < stylex.1 < stylex.2 < ...
+```
+
+Product-level StyleX styles always win over XDS component defaults without needing `!important` or extra specificity.
+
+## Key Difference from Source Build
+
+| | This example (dist + StyleX) | Source build |
+| ------------------- | ------------------------------------------- | -------------------------------------------- |
+| XDS CSS | Pre-built via `@import "@xds/core/xds.css"` | Compiled from source via StyleX babel plugin |
+| PostCSS `include` | `src/**/*` only (your code) | `src/**/*` + `node_modules/@xds/core/**/*` |
+| StyleX `aliases` | Not needed | Required for `createTheme` resolution |
+| `transpilePackages` | Not needed | Required in next.config |
+| Layer ordering | `useCSSLayers.before` declares XDS layers | `useCSSLayers: true` (XDS layers mixed in) |
+
+## Setup Steps
+
+### 1. Install dependencies
+
+```bash
+npm install @stylexjs/stylex @xds/core @xds/theme-default next react react-dom
+npm install --save-dev @stylexjs/babel-plugin @stylexjs/postcss-plugin \
+ @babel/preset-react @babel/preset-typescript typescript @types/react @types/react-dom
+```
+
+### 2. Browserslist
+
+```json
+{
+ "browserslist": ["last 1 Chrome version"]
+}
+```
+
+### 3. Babel config
+
+`babel.config.js` — StyleX for app-level styles only:
+
+```js
+module.exports = {
+ presets: ['next/babel'],
+ plugins: [
+ [
+ '@stylexjs/babel-plugin',
+ {
+ dev: process.env.NODE_ENV === 'development',
+ runtimeInjection: false,
+ genConditionalClasses: true,
+ treeshakeCompensation: true,
+ unstable_moduleResolution: {
+ type: 'commonJS',
+ rootDir: __dirname,
+ },
+ },
+ ],
+ ],
+};
+```
+
+> No `aliases` config needed — we're not compiling XDS source.
+
+### 4. PostCSS config
+
+`postcss.config.js` — scan your app source, declare XDS layers before StyleX layers:
+
+```js
+module.exports = {
+ plugins: {
+ '@stylexjs/postcss-plugin': {
+ include: ['src/**/*.{js,jsx,ts,tsx}'],
+ babelConfig: {
+ /* ... */
+ },
+ useCSSLayers: {
+ before: ['reset', 'xds-base', 'xds-theme'],
+ },
+ },
+ },
+};
+```
+
+### 5. CSS entry point
+
+`src/app/globals.css`:
+
+```css
+@import '@xds/core/reset.css';
+@import '@xds/core/xds.css';
+@import '@xds/theme-default/theme.css';
+
+@stylex;
+```
+
+### 6. Theme + Link provider
+
+```tsx
+'use client';
+import Link from 'next/link';
+import {XDSTheme} from '@xds/core/theme';
+import {XDSLinkProvider} from '@xds/core/Link';
+import {defaultTheme} from '@xds/theme-default/built';
+
+export function Providers({children}) {
+ return (
+ <XDSTheme theme={defaultTheme}>
+ <XDSLinkProvider component={Link}>{children}</XDSLinkProvider>
+ </XDSTheme>
+ );
+}
+```
+
+## Related
+
+- [Plain dist example](../example-nextjs/) — no CSS framework, inline styles for layout
+- [Dist + Tailwind example](../example-nextjs-tailwind/) — Tailwind for layout styles
diff --git a/apps/example-nextjs-stylex/babel.config.js b/apps/example-nextjs-stylex/babel.config.js
new file mode 100644
index 0000000000..c9c59376c9
--- /dev/null
+++ b/apps/example-nextjs-stylex/babel.config.js
@@ -0,0 +1,28 @@
+/* global module, require, process, __dirname */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const path = require('path');
+
+const dev = process.env.NODE_ENV !== 'production';
+
+module.exports = {
+ presets: ['next/babel'],
+ plugins: [
+ [
+ '@stylexjs/babel-plugin',
+ // See all options in the babel plugin configuration docs:
+ // https://stylexjs.com/docs/api/configuration/babel-plugin/
+ {
+ dev,
+ runtimeInjection: false,
+ enableInlinedConditionalMerge: true,
+ treeshakeCompensation: true,
+ aliases: {
+ '@/*': [path.join(__dirname, '*')],
+ },
+ unstable_moduleResolution: {
+ type: 'commonJS',
+ },
+ },
+ ],
+ ],
+};
diff --git a/apps/example-nextjs-stylex/next.config.mjs b/apps/example-nextjs-stylex/next.config.mjs
new file mode 100644
index 0000000000..4678774e6d
--- /dev/null
+++ b/apps/example-nextjs-stylex/next.config.mjs
@@ -0,0 +1,4 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {};
+
+export default nextConfig;
diff --git a/apps/example-nextjs-stylex/package.json b/apps/example-nextjs-stylex/package.json
new file mode 100644
index 0000000000..f6489f0b70
--- /dev/null
+++ b/apps/example-nextjs-stylex/package.json
@@ -0,0 +1,31 @@
+{
+ "name": "@xds/example-nextjs-stylex",
+ "version": "0.0.1",
+ "private": true,
+ "scripts": {
+ "dev": "next dev",
+ "build": "next build",
+ "start": "next start"
+ },
+ "dependencies": {
+ "@stylexjs/stylex": "^0.18.2",
+ "@xds/core": "*",
+ "@xds/theme-default": "*",
+ "next": "^15.5.15",
+ "react": "^19.2.5",
+ "react-dom": "^19.2.5"
+ },
+ "devDependencies": {
+ "@stylexjs/babel-plugin": "^0.18.2",
+ "@stylexjs/postcss-plugin": "^0.18.2",
+ "@babel/preset-react": "^7.25.0",
+ "@babel/preset-typescript": "^7.25.0",
+ "@types/react": "^19.2.14",
+ "@types/react-dom": "^19.2.3",
+ "typescript": "^5.7.0",
+ "autoprefixer": "^10.4.0"
+ },
+ "browserslist": [
+ "last 1 Chrome version"
+ ]
+}
diff --git a/apps/example-nextjs-stylex/postcss.config.js b/apps/example-nextjs-stylex/postcss.config.js
new file mode 100644
index 0000000000..251501274d
--- /dev/null
+++ b/apps/example-nextjs-stylex/postcss.config.js
@@ -0,0 +1,24 @@
+/* global module, require */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const babelConfig = require('./babel.config');
+
+module.exports = {
+ plugins: {
+ '@stylexjs/postcss-plugin': {
+ include: ['src/**/*.{js,jsx,ts,tsx}'],
+ babelConfig: {
+ babelrc: false,
+ parserOpts: {
+ plugins: ['typescript', 'jsx'],
+ },
+ plugins: babelConfig.plugins,
+ },
+ useCSSLayers: {
+ // Declare XDS dist layers before StyleX app layers so
+ // product styles always win over component defaults.
+ before: ['reset', 'xds-base', 'xds-theme'],
+ },
+ },
+ autoprefixer: {},
+ },
+};
diff --git a/apps/example-nextjs-stylex/src/app/globals.css b/apps/example-nextjs-stylex/src/app/globals.css
new file mode 100644
index 0000000000..c76d2bd483
--- /dev/null
+++ b/apps/example-nextjs-stylex/src/app/globals.css
@@ -0,0 +1,8 @@
+@import "@xds/core/reset.css";
+@import "@xds/core/xds.css";
+@import "@xds/theme-default/theme.css";
+
+/* StyleX app styles are injected here. The postcss plugin declares
+ reset, xds-base, and xds-theme as layersBefore so the full layer order
+ is: reset < xds-base < xds-theme < stylex app layers. */
+@stylex;
diff --git a/apps/example-nextjs-stylex/src/app/layout.tsx b/apps/example-nextjs-stylex/src/app/layout.tsx
new file mode 100644
index 0000000000..9580a96739
--- /dev/null
+++ b/apps/example-nextjs-stylex/src/app/layout.tsx
@@ -0,0 +1,19 @@
+import type {Metadata} from 'next';
+import './globals.css';
+import {Providers} from './providers';
+
+export const metadata: Metadata = {
+ title: 'XDS Example — Next.js + StyleX (Dist)',
+ description:
+ 'Reference example consuming @xds/core pre-built dist with StyleX for custom styles',
+};
+
+export default function RootLayout({children}: {children: React.ReactNode}) {
+ return (
+ <html lang="en">
+ <body>
+ <Providers>{children}</Providers>
+ </body>
+ </html>
+ );
+}
diff --git a/apps/example-nextjs-stylex/src/app/page.tsx b/apps/example-nextjs-stylex/src/app/page.tsx
new file mode 100644
index 0000000000..4ddbc11aba
--- /dev/null
+++ b/apps/example-nextjs-stylex/src/app/page.tsx
@@ -0,0 +1,121 @@
+'use client';
+
+import {useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {XDSVStack, XDSHStack} from '@xds/core/Layout';
+import {XDSButton} from '@xds/core/Button';
+import {XDSText, XDSHeading} from '@xds/core/Text';
+import {XDSTextInput} from '@xds/core/TextInput';
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSDivider} from '@xds/core';
+
+const styles = stylex.create({
+ main: {
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ minHeight: '100vh',
+ padding: '2rem',
+ },
+ container: {
+ maxWidth: 640,
+ width: '100%',
+ },
+ card: {
+ borderRadius: 8,
+ border: '1px solid var(--color-border)',
+ padding: '1rem',
+ backgroundColor: 'var(--color-background-body)',
+ },
+});
+
+export default function Home() {
+ const [email, setEmail] = useState('');
+
+ return (
+ <main {...stylex.props(styles.main)}>
+ <div {...stylex.props(styles.container)}>
+ <XDSVStack gap={6}>
+ <XDSVStack gap={2}>
+ <XDSHeading level={1}>XDS + StyleX (Dist Build)</XDSHeading>
+ <XDSText type="body" color="secondary">
+ This example consumes{' '}
+ <XDSText type="body" weight="bold">
+ @xds/core
+ </XDSText>{' '}
+ as a pre-built dist package — StyleX is only used for
+ product-level layout styles, not to compile XDS itself. XDS
+ handles components, theming, and design tokens.
+ </XDSText>
+ </XDSVStack>
+
+ <XDSDivider />
+
+ {/* Buttons */}
+ <XDSVStack gap={3}>
+ <XDSHeading level={2}>Buttons</XDSHeading>
+ <XDSHStack gap={3} vAlign="center">
+ <XDSButton label="Primary" variant="primary" />
+ <XDSButton label="Secondary" variant="secondary" />
+ <XDSButton label="Ghost" variant="ghost" />
+ </XDSHStack>
+ </XDSVStack>
+
+ <XDSDivider />
+
+ {/* Badges */}
+ <XDSVStack gap={3}>
+ <XDSHeading level={2}>Badges</XDSHeading>
+ <XDSHStack gap={3} vAlign="center">
+ <XDSBadge variant="info" label="Info" />
+ <XDSBadge variant="success" label="Success" />
+ <XDSBadge variant="warning" label="Warning" />
+ <XDSBadge variant="error" label="Error" />
+ </XDSHStack>
+ </XDSVStack>
+
+ <XDSDivider />
+
+ {/* Text Input */}
+ <XDSVStack gap={3}>
+ <XDSHeading level={2}>Text Input</XDSHeading>
+ <XDSTextInput
+ label="Email address"
+ placeholder="[email protected]"
+ value={email}
+ onChange={setEmail}
+ />
+ </XDSVStack>
+
+ <XDSDivider />
+
+ {/* StyleX custom styling */}
+ <XDSVStack gap={3}>
+ <XDSHeading level={2}>StyleX Integration</XDSHeading>
+ <div {...stylex.props(styles.card)}>
+ <XDSText type="body">
+ This card uses StyleX for layout with XDS design tokens via CSS
+ custom properties. StyleX compiles your app styles at build time
+ while XDS component CSS comes pre-built from the dist package.
+ </XDSText>
+ </div>
+ </XDSVStack>
+
+ <XDSDivider />
+
+ {/* Typography */}
+ <XDSVStack gap={3}>
+ <XDSHeading level={2}>Typography</XDSHeading>
+ <XDSText type="large" weight="bold">
+ Large bold text
+ </XDSText>
+ <XDSText type="body">Default body text</XDSText>
+ <XDSText type="supporting" color="secondary">
+ Supporting text in secondary color
+ </XDSText>
+ </XDSVStack>
+ </XDSVStack>
+ </div>
+ </main>
+ );
+}
diff --git a/apps/example-nextjs-stylex/src/app/providers.tsx b/apps/example-nextjs-stylex/src/app/providers.tsx
new file mode 100644
index 0000000000..2df97556c1
--- /dev/null
+++ b/apps/example-nextjs-stylex/src/app/providers.tsx
@@ -0,0 +1,14 @@
+'use client';
+
+import Link from 'next/link';
+import {XDSTheme} from '@xds/core/theme';
+import {XDSLinkProvider} from '@xds/core/Link';
+import {defaultTheme} from '@xds/theme-default/built';
+
+export function Providers({children}: {children: React.ReactNode}) {
+ return (
+ <XDSTheme theme={defaultTheme}>
+ <XDSLinkProvider component={Link}>{children}</XDSLinkProvider>
+ </XDSTheme>
+ );
+}
diff --git a/apps/example-nextjs-stylex/tsconfig.json b/apps/example-nextjs-stylex/tsconfig.json
new file mode 100644
index 0000000000..d2bba220e4
--- /dev/null
+++ b/apps/example-nextjs-stylex/tsconfig.json
@@ -0,0 +1,40 @@
+{
+ "compilerOptions": {
+ "target": "ES2017",
+ "lib": [
+ "dom",
+ "dom.iterable",
+ "esnext"
+ ],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "preserve",
+ "incremental": true,
+ "plugins": [
+ {
+ "name": "next"
+ }
+ ],
+ "paths": {
+ "@/*": [
+ "./src/*"
+ ]
+ }
+ },
+ "include": [
+ "next-env.d.ts",
+ "**/*.ts",
+ "**/*.tsx",
+ ".next/types/**/*.ts"
+ ],
+ "exclude": [
+ "node_modules"
+ ]
+}
diff --git a/apps/example-nextjs-tailwind/next.config.mjs b/apps/example-nextjs-tailwind/next.config.mjs
index 8eda3ae9ec..4678774e6d 100644
--- a/apps/example-nextjs-tailwind/next.config.mjs
+++ b/apps/example-nextjs-tailwind/next.config.mjs
@@ -1,8 +1,4 @@
/** @type {import('next').NextConfig} */
-const nextConfig = {
- typescript: {
- ignoreBuildErrors: true,
- },
-};
+const nextConfig = {};
export default nextConfig;
diff --git a/apps/example-nextjs-tailwind/src/app/globals.css b/apps/example-nextjs-tailwind/src/app/globals.css
index c51dd5ca9c..27813fcb7c 100644
--- a/apps/example-nextjs-tailwind/src/app/globals.css
+++ b/apps/example-nextjs-tailwind/src/app/globals.css
@@ -1,11 +1,8 @@
-@import "tailwindcss";
+@layer theme, base, components, utilities;
+
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/preflight.css" layer(base);
@import "@xds/core/reset.css";
+@import "@xds/core/xds.css";
@import "@xds/theme-default/theme.css";
-
-/* Component CSS is now auto-imported via JS side-effect imports.
- * Each `import { XDSButton } from '@xds/core/Button'` pulls in
- * common.css (shared, loaded once) + Button/styles.css (unique).
- *
- * For the all-in-one approach, you can still use:
- * @import "@xds/core/xds.css";
- */
+@import "tailwindcss/utilities.css" layer(utilities);
diff --git a/apps/example-nextjs-tailwind/src/app/providers.tsx b/apps/example-nextjs-tailwind/src/app/providers.tsx
index 329a994036..2df97556c1 100644
--- a/apps/example-nextjs-tailwind/src/app/providers.tsx
+++ b/apps/example-nextjs-tailwind/src/app/providers.tsx
@@ -1,8 +1,14 @@
'use client';
+import Link from 'next/link';
import {XDSTheme} from '@xds/core/theme';
+import {XDSLinkProvider} from '@xds/core/Link';
import {defaultTheme} from '@xds/theme-default/built';
export function Providers({children}: {children: React.ReactNode}) {
- return <XDSTheme theme={defaultTheme}>{children}</XDSTheme>;
+ return (
+ <XDSTheme theme={defaultTheme}>
+ <XDSLinkProvider component={Link}>{children}</XDSLinkProvider>
+ </XDSTheme>
+ );
}
diff --git a/apps/example-nextjs/README.md b/apps/example-nextjs/README.md
index 90c652f4cd..375dd9a8a4 100644
--- a/apps/example-nextjs/README.md
+++ b/apps/example-nextjs/README.md
@@ -1,158 +1,75 @@
-# XDS Example — Next.js
+# XDS Example — Next.js (Dist)
-Reference application for consuming **@xds/core** as a source distribution in a Next.js project.
+Reference application for consuming **@xds/core** as a pre-built dist package in a Next.js project.
-XDS ships as raw TypeScript + StyleX source. Consumers compile it at the application level — there's no pre-built CSS or JS bundle. This example shows the complete setup.
+No StyleX build plugin needed — XDS ships pre-compiled CSS and JS. This is the simplest way to get started.
## Setup Steps
### 1. Install dependencies
```bash
-npm install @stylexjs/stylex @xds/core next react react-dom
-npm install --save-dev @stylexjs/babel-plugin @stylexjs/postcss-plugin \
- @babel/preset-react @babel/preset-typescript typescript @types/react @types/react-dom
+npm install @xds/core @xds/theme-default next react react-dom
+npm install --save-dev @types/react @types/react-dom typescript
```
-### 2. Browserslist
+### 2. CSS imports
-Add a `browserslist` to `package.json` so that Next.js (and its internal lightningcss) targets modern browsers. Without this, lightningcss may lower `light-dark()` into polyfill variables that break XDS theming:
-
-```json
-{
- "browserslist": ["last 1 Chrome version"]
-}
-```
-
-> For internal tools targeting latest Chrome, `"last 1 Chrome version"` is sufficient. For broader browser support, use targets that include Chrome 123+ / Firefox 120+ / Safari 17.5+ (when `light-dark()` shipped).
-
-### 3. Babel config
-
-`babel.config.js` — configure StyleX as a **plugin** (not a preset) with `next/babel`:
-
-```js
-const path = require('path');
-
-module.exports = {
- presets: ['next/babel'],
- plugins: [
- [
- '@stylexjs/babel-plugin',
- {
- dev: process.env.NODE_ENV === 'development',
- runtimeInjection: false,
- genConditionalClasses: true,
- treeshakeCompensation: true,
- aliases: {
- '@xds/core/*': [path.join(__dirname, 'node_modules/@xds/core/*')],
- '@xds/core': [path.join(__dirname, 'node_modules/@xds/core')],
- },
- unstable_moduleResolution: {
- type: 'commonJS',
- rootDir: __dirname,
- },
- },
- ],
- ],
-};
-```
-
-> **Important:** The `aliases` config is required for `stylex.createTheme` to resolve token definitions correctly. Without it, theme overrides silently fail.
-
-### 4. PostCSS config
-
-`postcss.config.js` — this is how Next.js extracts StyleX CSS:
-
-```js
-const babelConfig = require('./babel.config');
-
-module.exports = {
- plugins: {
- '@stylexjs/postcss-plugin': {
- include: [
- 'src/**/*.{js,jsx,ts,tsx}',
- 'node_modules/@xds/core/**/*.{ts,tsx}',
- ],
- babelConfig: {
- babelrc: false,
- parserOpts: {plugins: ['typescript', 'jsx']},
- presets: [
- ['@babel/preset-react', {runtime: 'automatic'}],
- '@babel/preset-typescript',
- ],
- plugins: babelConfig.plugins,
- },
- useCSSLayers: true,
- },
- },
-};
-```
-
-### 5. CSS entry point with `@stylex;` directive
-
-`src/app/globals.css`:
+`src/app/globals.css` — import the reset, component styles, and theme:
```css
-@stylex;
-```
-
-Import it in your root layout, along with the base reset and theme CSS:
-
-```tsx
-import '@xds/core/reset.css';
-import '@xds/theme-default/theme.css';
-import './globals.css';
+@import '@xds/core/reset.css';
+@import '@xds/core/xds.css';
+@import '@xds/theme-default/theme.css';
```
The CSS import order matters:
1. `reset.css` — baseline resets (`@layer reset`)
-2. `theme.css` — theme token overrides (`@layer xds.theme`)
-3. `globals.css` — StyleX extraction (`@stylex;` directive)
+2. `xds.css` — all component styles (`@layer xds-base`)
+3. `theme.css` — theme token overrides (`@layer xds-theme`)
-### 6. Next.js config
+Import the CSS file in your root layout:
-`next.config.mjs` — add `transpilePackages` so Next.js compiles XDS source:
-
-```js
-const nextConfig = {
- transpilePackages: ['@xds/core', '@xds/theme-default'],
-};
-export default nextConfig;
+```tsx
+import './globals.css';
```
-### 7. Theme provider (client boundary)
+### 3. Theme + Link provider (client boundary)
```tsx
// src/app/providers.tsx
'use client';
+import Link from 'next/link';
import {XDSTheme} from '@xds/core/theme';
-import {defaultTheme} from '@xds/theme-default';
+import {XDSLinkProvider} from '@xds/core/Link';
+import {defaultTheme} from '@xds/theme-default/built';
export function Providers({children}) {
- return <XDSTheme theme={defaultTheme}>{children}</XDSTheme>;
+ return (
+ <XDSTheme theme={defaultTheme}>
+ <XDSLinkProvider component={Link}>{children}</XDSLinkProvider>
+ </XDSTheme>
+ );
}
```
+`XDSLinkProvider` wires up Next.js client-side navigation for all XDS link-based components (Link, Button with href, TopNav, SideNav, Breadcrumbs, TabList).
+
## Gotchas
-| Issue | Symptom | Fix |
-| ----------------------------------- | ------------------------------------------- | ----------------------------------------------------------------- |
-| Missing `browserslist` | Colors broken — `light-dark()` gets lowered | Add `"browserslist": ["last 1 Chrome version"]` to `package.json` |
-| Missing `@stylex;` directive | PostCSS produces empty CSS with no error | Add `@stylex;` to your CSS entry file |
-| PostCSS `include` doesn't cover XDS | XDS component styles are missing | Add `node_modules/@xds/core/**/*.{ts,tsx}` to `include` |
-| Missing `aliases` in babel config | `createTheme` token overrides silently fail | Add `aliases` mapping for `@xds/core` and `@xds/core/*` |
-| No `'use client'` on theme provider | Server component error from `createContext` | Mark the provider file with `'use client'` |
-| StyleX as preset instead of plugin | Build errors or missing styles | Use `plugins` array, not `presets`, for `@stylexjs/babel-plugin` |
+| Issue | Symptom | Fix |
+| ----------------------------- | ------------------------------------------- | ------------------------------------------ |
+| Wrong CSS import order | Missing theme tokens or broken layers | Import reset → xds → theme in that order |
+| No `'use client'` on provider | Server component error from `createContext` | Mark the provider file with `'use client'` |
## Testing outside the monorepo
-This example lives in the XDS monorepo for convenience, but it should be representative of a real app consuming `@xds/core` from npm. Monorepo workspace resolution can silently bypass issues that external consumers hit (missing dependencies, wrong include paths, different CSS pipeline behavior).
+This example lives in the XDS monorepo for convenience, but it should be representative of a real app consuming `@xds/core` from npm. Monorepo workspace resolution can silently bypass issues that external consumers hit.
**Before merging changes to this example, test it as an external consumer** — see the [Testing Example Apps](https://github.com/facebookexperimental/xds/wiki/Testing-Example-Apps) wiki page for the full procedure.
## Related
- [Issue #145 — Add example-nextjs project](https://github.com/facebookexperimental/xds/issues/145)
-- [StyleX examples](https://github.com/facebook/stylex/tree/main/examples)
-- [Working prototype (cixzhang/xds_sandbox)](https://github.com/cixzhang/xds_sandbox)
+- [XDS + Tailwind example](../example-nextjs-tailwind/) — same dist approach with Tailwind for custom layout styles
diff --git a/apps/example-nextjs/babel.config.js b/apps/example-nextjs/babel.config.js
deleted file mode 100644
index 9312f6b6ba..0000000000
--- a/apps/example-nextjs/babel.config.js
+++ /dev/null
@@ -1,25 +0,0 @@
-/* global module, process, __dirname */
-const path = require('path');
-
-module.exports = {
- presets: ['next/babel'],
- plugins: [
- [
- '@stylexjs/babel-plugin',
- {
- dev: process.env.NODE_ENV === 'development',
- runtimeInjection: false,
- genConditionalClasses: true,
- treeshakeCompensation: true,
- aliases: {
- '@xds/core/*': [path.join(__dirname, 'node_modules/@xds/core/*')],
- '@xds/core': [path.join(__dirname, 'node_modules/@xds/core')],
- },
- unstable_moduleResolution: {
- type: 'commonJS',
- rootDir: __dirname,
- },
- },
- ],
- ],
-};
diff --git a/apps/example-nextjs/next.config.mjs b/apps/example-nextjs/next.config.mjs
index c616176c79..4678774e6d 100644
--- a/apps/example-nextjs/next.config.mjs
+++ b/apps/example-nextjs/next.config.mjs
@@ -1,6 +1,4 @@
/** @type {import('next').NextConfig} */
-const nextConfig = {
- transpilePackages: ['@xds/core', '@xds/theme-default'],
-};
+const nextConfig = {};
export default nextConfig;
diff --git a/apps/example-nextjs/package.json b/apps/example-nextjs/package.json
index feccf0dce6..31d8495122 100644
--- a/apps/example-nextjs/package.json
+++ b/apps/example-nextjs/package.json
@@ -8,7 +8,6 @@
"start": "next start"
},
"dependencies": {
- "@stylexjs/stylex": "^0.18.2",
"@xds/core": "*",
"@xds/theme-default": "*",
"next": "^15.5.15",
@@ -16,15 +15,8 @@
"react-dom": "^19.2.5"
},
"devDependencies": {
- "@babel/preset-react": "^7.25.0",
- "@babel/preset-typescript": "^7.25.0",
- "@stylexjs/babel-plugin": "^0.18.2",
- "@stylexjs/postcss-plugin": "^0.18.2",
"@types/react": "^19.2.14",
"@types/react-dom": "^19.2.3",
"typescript": "^5.7.0"
- },
- "browserslist": [
- "last 1 Chrome version"
- ]
+ }
}
diff --git a/apps/example-nextjs/postcss.config.js b/apps/example-nextjs/postcss.config.js
deleted file mode 100644
index f3bab9eb4e..0000000000
--- a/apps/example-nextjs/postcss.config.js
+++ /dev/null
@@ -1,25 +0,0 @@
-/* global module */
-const babelConfig = require('./babel.config');
-
-module.exports = {
- plugins: {
- '@stylexjs/postcss-plugin': {
- include: [
- 'src/**/*.{js,jsx,ts,tsx}',
- 'node_modules/@xds/core/**/*.{ts,tsx}',
- ],
- babelConfig: {
- babelrc: false,
- parserOpts: {
- plugins: ['typescript', 'jsx'],
- },
- presets: [
- ['@babel/preset-react', {runtime: 'automatic'}],
- '@babel/preset-typescript',
- ],
- plugins: babelConfig.plugins,
- },
- useCSSLayers: true,
- },
- },
-};
diff --git a/apps/example-nextjs/src/app/globals.css b/apps/example-nextjs/src/app/globals.css
index 867d14b250..99dc56b92b 100644
--- a/apps/example-nextjs/src/app/globals.css
+++ b/apps/example-nextjs/src/app/globals.css
@@ -1 +1,3 @@
-@stylex;
+@import "@xds/core/reset.css";
+@import "@xds/core/xds.css";
+@import "@xds/theme-default/theme.css";
diff --git a/apps/example-nextjs/src/app/layout.tsx b/apps/example-nextjs/src/app/layout.tsx
index 5a05df40c3..d0240b151d 100644
--- a/apps/example-nextjs/src/app/layout.tsx
+++ b/apps/example-nextjs/src/app/layout.tsx
@@ -1,13 +1,11 @@
import type {Metadata} from 'next';
-import '@xds/core/reset.css';
-import '@xds/theme-default/theme.css';
import './globals.css';
import {Providers} from './providers';
export const metadata: Metadata = {
- title: 'XDS Example — Next.js',
+ title: 'XDS Example — Next.js (Dist)',
description:
- 'Reference example for consuming @xds/core as a source distribution',
+ 'Reference example for consuming @xds/core as a pre-built dist package',
};
export default function RootLayout({children}: {children: React.ReactNode}) {
diff --git a/apps/example-nextjs/src/app/page.tsx b/apps/example-nextjs/src/app/page.tsx
index 48ddbcedb3..2bca15ed7c 100644
--- a/apps/example-nextjs/src/app/page.tsx
+++ b/apps/example-nextjs/src/app/page.tsx
@@ -1,7 +1,5 @@
'use client';
-import {useState} from 'react';
-import * as stylex from '@stylexjs/stylex';
import {XDSVStack, XDSHStack} from '@xds/core/Layout';
import {XDSButton} from '@xds/core/Button';
import {XDSText, XDSHeading} from '@xds/core/Text';
@@ -9,36 +7,28 @@ import {XDSTextInput} from '@xds/core/TextInput';
import {XDSBadge} from '@xds/core/Badge';
import {XDSDivider} from '@xds/core';
-const styles = stylex.create({
- main: {
- display: 'flex',
- alignItems: 'center',
- justifyContent: 'center',
- minHeight: '100vh',
- padding: '2rem',
- },
- container: {
- maxWidth: 640,
- width: '100%',
- },
-});
-
export default function Home() {
- const [email, setEmail] = useState('');
-
return (
- <main {...stylex.props(styles.main)}>
- <div {...stylex.props(styles.container)}>
+ <main
+ style={{
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ minHeight: '100vh',
+ padding: '2rem',
+ }}>
+ <div style={{maxWidth: 640, width: '100%'}}>
<XDSVStack gap={6}>
<XDSVStack gap={2}>
- <XDSHeading level={1}>XDS Example — Next.js</XDSHeading>
+ <XDSHeading level={1}>XDS Example — Next.js (Dist)</XDSHeading>
<XDSText type="body" color="secondary">
- This is a reference example for consuming{' '}
+ This example consumes{' '}
<XDSText type="body" weight="bold">
@xds/core
</XDSText>{' '}
- as a source distribution in a Next.js application. Components are
- compiled from raw TypeScript source using StyleX at build time.
+ as a pre-built dist package — no StyleX build plugin needed. Plain
+ inline styles handle layout. XDS handles components, theming, and
+ design tokens.
</XDSText>
</XDSVStack>
@@ -72,12 +62,7 @@ export default function Home() {
{/* Text Input */}
<XDSVStack gap={3}>
<XDSHeading level={2}>Text Input</XDSHeading>
- <XDSTextInput
- label="Email address"
- placeholder="[email protected]"
- value={email}
- onChange={setEmail}
- />
+ <XDSTextInput label="Email address" placeholder="[email protected]" />
</XDSVStack>
<XDSDivider />
diff --git a/apps/example-nextjs/src/app/providers.tsx b/apps/example-nextjs/src/app/providers.tsx
index 329a994036..2df97556c1 100644
--- a/apps/example-nextjs/src/app/providers.tsx
+++ b/apps/example-nextjs/src/app/providers.tsx
@@ -1,8 +1,14 @@
'use client';
+import Link from 'next/link';
import {XDSTheme} from '@xds/core/theme';
+import {XDSLinkProvider} from '@xds/core/Link';
import {defaultTheme} from '@xds/theme-default/built';
export function Providers({children}: {children: React.ReactNode}) {
- return <XDSTheme theme={defaultTheme}>{children}</XDSTheme>;
+ return (
+ <XDSTheme theme={defaultTheme}>
+ <XDSLinkProvider component={Link}>{children}</XDSLinkProvider>
+ </XDSTheme>
+ );
}
diff --git a/yarn.lock b/yarn.lock
index e94e2f73ca..974a4b3db5 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2807,6 +2807,17 @@ ast-types@^0.16.1:
dependencies:
tslib "^2.0.1"
+autoprefixer@^10.4.0:
+ version "10.5.0"
+ resolved "https://registry.yarnpkg.com/autoprefixer/-/autoprefixer-10.5.0.tgz#33d87e443430f020a0f85319d6ff1593cb291be9"
+ integrity sha512-FMhOoZV4+qR6aTUALKX2rEqGG+oyATvwBt9IIzVR5rMa2HRWPkxf+P+PAJLD1I/H5/II+HuZcBJYEFBpq39ong==
+ dependencies:
+ browserslist "^4.28.2"
+ caniuse-lite "^1.0.30001787"
+ fraction.js "^5.3.4"
+ picocolors "^1.1.1"
+ postcss-value-parser "^4.2.0"
+
available-typed-arrays@^1.0.7:
version "1.0.7"
resolved "https://registry.npmjs.org/available-typed-arrays/-/available-typed-arrays-1.0.7.tgz"
@@ -2836,6 +2847,11 @@ balanced-match@^4.0.2:
resolved "https://registry.yarnpkg.com/balanced-match/-/balanced-match-4.0.4.tgz#bfb10662feed8196a2c62e7c68e17720c274179a"
integrity sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==
+baseline-browser-mapping@^2.10.12:
+ version "2.10.19"
+ resolved "https://registry.yarnpkg.com/baseline-browser-mapping/-/baseline-browser-mapping-2.10.19.tgz#7697721c22f94f66195d0c34299b1a91e3299493"
+ integrity sha512-qCkNLi2sfBOn8XhZQ0FXsT1Ki/Yo5P90hrkRamVFRS7/KV9hpfA4HkoWNU152+8w0zPjnxo5psx5NL3PSGgv5g==
+
baseline-browser-mapping@^2.9.0:
version "2.9.14"
resolved "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.9.14.tgz"
@@ -2907,6 +2923,17 @@ browserslist@^4.24.0:
node-releases "^2.0.27"
update-browserslist-db "^1.2.0"
+browserslist@^4.28.2:
+ version "4.28.2"
+ resolved "https://registry.yarnpkg.com/browserslist/-/browserslist-4.28.2.tgz#f50b65362ef48974ca9f50b3680566d786b811d2"
+ integrity sha512-48xSriZYYg+8qXna9kwqjIVzuQxi+KYWp2+5nCYnYKPTr0LvD89Jqk2Or5ogxz0NUMfIjhh2lIUX/LyX9B4oIg==
+ dependencies:
+ baseline-browser-mapping "^2.10.12"
+ caniuse-lite "^1.0.30001782"
+ electron-to-chromium "^1.5.328"
+ node-releases "^2.0.36"
+ update-browserslist-db "^1.2.3"
+
buffer-from@^1.0.0:
version "1.1.2"
resolved "https://registry.npmjs.org/buffer-from/-/buffer-from-1.1.2.tgz"
@@ -2960,6 +2987,11 @@ caniuse-lite@^1.0.30001579, caniuse-lite@^1.0.30001759:
resolved "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001769.tgz"
integrity sha512-BCfFL1sHijQlBGWBMuJyhZUhzo7wer5sVj9hqekB/7xn0Ypy+pER/edCYQm4exbXj4WiySGp40P8UuTh6w1srg==
+caniuse-lite@^1.0.30001782, caniuse-lite@^1.0.30001787:
+ version "1.0.30001788"
+ resolved "https://registry.yarnpkg.com/caniuse-lite/-/caniuse-lite-1.0.30001788.tgz#31e97d1bfec332b3f2d7eea7781460c97629b3bf"
+ integrity sha512-6q8HFp+lOQtcf7wBK+uEenxymVWkGKkjFpCvw5W25cmMwEDU45p1xQFBQv8JDlMMry7eNxyBaR+qxgmTUZkIRQ==
+
chai@^5.1.1, chai@^5.1.2:
version "5.3.3"
resolved "https://registry.npmjs.org/chai/-/chai-5.3.3.tgz"
@@ -3388,6 +3420,11 @@ electron-to-chromium@^1.5.263:
resolved "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.267.tgz"
integrity sha512-0Drusm6MVRXSOJpGbaSVgcQsuB4hEkMpHXaVstcPmhu5LIedxs1xNK/nIxmQIU/RPC0+1/o0AVZfBTkTNJOdUw==
+electron-to-chromium@^1.5.328:
+ version "1.5.339"
+ resolved "https://registry.yarnpkg.com/electron-to-chromium/-/electron-to-chromium-1.5.339.tgz#d797bf5f222a7f6241a42b43a97bf52ff43947f1"
+ integrity sha512-Is+0BBHJ4NrdpAYiperrmp53pLywG/yV/6lIMTAnhxvzj/Cmn5Q/ogSHC6AKe7X+8kPLxxFk0cs5oc/3j/fxIg==
+
emoji-regex@^10.3.0:
version "10.6.0"
resolved "https://registry.yarnpkg.com/emoji-regex/-/emoji-regex-10.6.0.tgz#bf3d6e8f7f8fd22a65d9703475bc0147357a6b0d"
@@ -3870,6 +3907,11 @@ foreground-child@^3.1.0:
cross-spawn "^7.0.6"
signal-exit "^4.0.1"
+fraction.js@^5.3.4:
+ version "5.3.4"
+ resolved "https://registry.yarnpkg.com/fraction.js/-/fraction.js-5.3.4.tgz#8c0fcc6a9908262df4ed197427bdeef563e0699a"
+ integrity sha512-1X1NTtiJphryn/uLQz3whtY6jK3fTqoE3ohKs0tT+Ujr1W59oopxmoEh7Lu5p6vBaPbgoM0bzveAW4Qi5RyWDQ==
+
fs-extra@^7.0.1:
version "7.0.1"
resolved "https://registry.npmjs.org/fs-extra/-/fs-extra-7.0.1.tgz"
@@ -4863,6 +4905,11 @@ node-releases@^2.0.27:
resolved "https://registry.npmjs.org/node-releases/-/node-releases-2.0.27.tgz"
integrity sha512-nmh3lCkYZ3grZvqcCH+fjmQ7X+H0OeZgP40OierEaAptX4XofMh5kwNbWh7lBduUzCcV/8kZ+NDLCwm2iorIlA==
+node-releases@^2.0.36:
+ version "2.0.37"
+ resolved "https://registry.yarnpkg.com/node-releases/-/node-releases-2.0.37.tgz#9bd4f10b77ba39c2b9402d4e8399c482a797f671"
+ integrity sha512-1h5gKZCF+pO/o3Iqt5Jp7wc9rH3eJJ0+nh/CIoiRwjRxde/hAHyLPXYN4V3CqKAbiZPSeJFSWHmJsbkicta0Eg==
+
object-assign@^4.0.1, object-assign@^4.1.1:
version "4.1.1"
resolved "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz"
@@ -5094,7 +5141,7 @@ postcss-load-config@^6.0.1:
dependencies:
lilconfig "^3.1.1"
-postcss-value-parser@^4.1.0:
+postcss-value-parser@^4.1.0, postcss-value-parser@^4.2.0:
version "4.2.0"
resolved "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz"
integrity sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==
@@ -5122,12 +5169,7 @@ prelude-ls@^1.2.1:
resolved "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz"
integrity sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==
-prettier@^2.7.1:
- version "2.8.8"
- resolved "https://registry.yarnpkg.com/prettier/-/prettier-2.8.8.tgz#e8c5d7e98a4305ffe3de2e1fc4aca1a71c28b1da"
- integrity sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==
-
-prettier@^3.8.2:
+prettier@^2.7.1, prettier@^3.8.2:
version "3.8.2"
resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.8.2.tgz#4f52e502193c9aa5b384c3d00852003e551bbd9f"
integrity sha512-8c3mgTe0ASwWAJK+78dpviD+A8EqhndQPUBpNUIPt6+xWlIigCwfN01lWr9MAede4uqXGTEKeQWTvzb3vjia0Q==
@@ -5932,7 +5974,7 @@ unplugin@^2.3.11:
picomatch "^4.0.3"
webpack-virtual-modules "^0.6.2"
-update-browserslist-db@^1.2.0:
+update-browserslist-db@^1.2.0, update-browserslist-db@^1.2.3:
version "1.2.3"
resolved "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz"
integrity sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==