Skip to content

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

TypeScript

feat(docsite): add Vercel Analytics with typed event tracking (#2611)

Cindy Zhangb9ba95001c32
diff --git a/apps/docsite/package.json b/apps/docsite/package.json
index 06e9b4c372..2620a24601 100644
--- a/apps/docsite/package.json
+++ b/apps/docsite/package.json
@@ -17,6 +17,7 @@
"@modelcontextprotocol/sdk": "^1.29.0",
"@monaco-editor/react": "^4.7.0",
"@stylexjs/stylex": "^0.18.3",
+ "@vercel/analytics": "^2.0.1",
"@xds/cli": "*",
"@xds/core": "*",
"@xds/theme-butter": "*",
diff --git a/apps/docsite/src/app/(site)/templates/page.tsx b/apps/docsite/src/app/(site)/templates/page.tsx
index 3403670d78..460d45d9d2 100644
--- a/apps/docsite/src/app/(site)/templates/page.tsx
+++ b/apps/docsite/src/app/(site)/templates/page.tsx
@@ -21,6 +21,7 @@ import {TemplateThumbnail} from '../../../components/TemplateThumbnail';
import {buildPlaygroundHref} from '../../../components/playgroundLink';
import {TemplatePreviewDialog} from '../../../components/TemplatePreviewDialog';
import type {TemplatePreviewItem} from '../../../components/TemplatePreviewDialog';
+import {trackOpenPlayground, trackView} from '../../../lib/analytics';
const GALLERY_MAX_WIDTH = 1600;
const CARD_MIN_WIDTH = 480;
@@ -112,7 +113,9 @@ const GROUP_LABELS: Record<string, string> = {
* Standalone categories without a separator (e.g. 'Settings') are their own
* group. Untagged templates fall under 'Other'. */
function groupOf(category: string): string {
- if (!category) {return OTHER_GROUP;}
+ if (!category) {
+ return OTHER_GROUP;
+ }
const idx = category.indexOf(' - ');
return idx === -1 ? category : category.slice(0, idx);
}
@@ -144,13 +147,18 @@ export default function TemplatesPage() {
source: t.source,
};
const list = byGroup.get(group);
- if (list) {list.push(item);}
- else {byGroup.set(group, [item]);}
+ if (list) {
+ list.push(item);
+ } else {
+ byGroup.set(group, [item]);
+ }
}
const rank = (g: string) => {
const i = GROUP_ORDER.indexOf(g);
- if (i !== -1) {return i;}
+ if (i !== -1) {
+ return i;
+ }
return g === OTHER_GROUP ? Number.MAX_SAFE_INTEGER : GROUP_ORDER.length;
};
@@ -191,7 +199,8 @@ export default function TemplatesPage() {
const pathname = usePathname();
const previewSlug = searchParams.get('preview');
- const openIndex = previewSlug != null ? (indexBySlug.get(previewSlug) ?? null) : null;
+ const openIndex =
+ previewSlug != null ? (indexBySlug.get(previewSlug) ?? null) : null;
const setOpenIndex = useCallback(
(index: number | null) => {
@@ -211,14 +220,23 @@ export default function TemplatesPage() {
(slug: string) => {
const i = indexBySlug.get(slug);
if (i !== undefined) {
+ const item = flatItems[i];
+ trackView({
+ page: 'templates',
+ item: item.slug,
+ category: item.category,
+ });
setOpenIndex(i);
}
},
- [indexBySlug, setOpenIndex],
+ [indexBySlug, setOpenIndex, flatItems],
);
return (
- <XDSSection maxWidth={GALLERY_MAX_WIDTH} padding={6} xstyle={styles.section}>
+ <XDSSection
+ maxWidth={GALLERY_MAX_WIDTH}
+ padding={6}
+ xstyle={styles.section}>
<XDSVStack gap={8}>
<XDSVStack gap={2} style={{alignItems: 'center'}}>
<XDSHeading level={1} type="display-2" xstyle={styles.heroTitle}>
@@ -256,62 +274,65 @@ export default function TemplatesPage() {
cursor: 'pointer',
} as React.CSSProperties
}>
- <XDSOverlay
- showOn="hover"
- scrim="dark"
- content={
- <div {...stylex.props(styles.overlayInner)}>
- <XDSVStack gap={2}>
- <XDSVStack gap={0.5}>
- <XDSHeading
- level={3}
- style={{color: '#fff'}}>
- {item.name}
- </XDSHeading>
- <XDSText
- type="body"
- style={{color: 'rgba(255,255,255,0.7)'}}>
- {item.description.slice(0, 80)}
- {item.description.length > 80 ? '\u2026' : ''}
- </XDSText>
- </XDSVStack>
- {/* Stop card-level click/keys from firing for
+ <XDSOverlay
+ showOn="hover"
+ scrim="dark"
+ content={
+ <div {...stylex.props(styles.overlayInner)}>
+ <XDSVStack gap={2}>
+ <XDSVStack gap={0.5}>
+ <XDSHeading level={3} style={{color: '#fff'}}>
+ {item.name}
+ </XDSHeading>
+ <XDSText
+ type="body"
+ style={{color: 'rgba(255,255,255,0.7)'}}>
+ {item.description.slice(0, 80)}
+ {item.description.length > 80 ? '\u2026' : ''}
+ </XDSText>
+ </XDSVStack>
+ {/* Stop card-level click/keys from firing for
the action buttons so each keeps its own
behavior (the card itself opens the preview). */}
- <div
- onClick={e => e.stopPropagation()}
- onKeyDown={e => e.stopPropagation()}>
- <XDSHStack gap={2}>
+ <div
+ onClick={e => e.stopPropagation()}
+ onKeyDown={e => e.stopPropagation()}>
+ <XDSHStack gap={2}>
+ <XDSButton
+ label="Preview"
+ variant="secondary"
+ onClick={() => openPreview(item.slug)}
+ />
+ {item.source && (
<XDSButton
- label="Preview"
+ label="Open in Playground"
variant="secondary"
- onClick={() => openPreview(item.slug)}
+ onClick={() => {
+ trackOpenPlayground({
+ page: 'templates',
+ item: item.slug,
+ category: groupOf(item.category),
+ });
+ window.location.href =
+ buildPlaygroundHref(item.source);
+ }}
/>
- {item.source && (
- <XDSButton
- label="Open in Playground"
- variant="secondary"
- onClick={() => {
- window.location.href =
- buildPlaygroundHref(item.source);
- }}
- />
- )}
- </XDSHStack>
- </div>
- </XDSVStack>
- </div>
- }>
- {item.isReady ? (
- <TemplateThumbnail slug={item.slug} />
- ) : (
- <div {...stylex.props(styles.cardImage)}>
- <div {...stylex.props(styles.comingSoon)}>
- <XDSBadge label="Coming Soon" variant="info" />
+ )}
+ </XDSHStack>
</div>
+ </XDSVStack>
+ </div>
+ }>
+ {item.isReady ? (
+ <TemplateThumbnail slug={item.slug} />
+ ) : (
+ <div {...stylex.props(styles.cardImage)}>
+ <div {...stylex.props(styles.comingSoon)}>
+ <XDSBadge label="Coming Soon" variant="info" />
</div>
- )}
- </XDSOverlay>
+ </div>
+ )}
+ </XDSOverlay>
</XDSCard>
))}
</div>
diff --git a/apps/docsite/src/app/layout.tsx b/apps/docsite/src/app/layout.tsx
index 5adefd060f..d8695093f5 100644
--- a/apps/docsite/src/app/layout.tsx
+++ b/apps/docsite/src/app/layout.tsx
@@ -1,6 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
import type {Metadata} from 'next';
+import {Analytics} from '@vercel/analytics/react';
import './globals.css';
import {Providers} from './providers';
@@ -36,6 +37,7 @@ export default function RootLayout({children}: {children: React.ReactNode}) {
/>
</head>
<body>
+ <Analytics />
<Providers>{children}</Providers>
</body>
</html>
diff --git a/apps/docsite/src/app/playground/PlaygroundClient.tsx b/apps/docsite/src/app/playground/PlaygroundClient.tsx
index 2ebc35fae3..d1cba07785 100644
--- a/apps/docsite/src/app/playground/PlaygroundClient.tsx
+++ b/apps/docsite/src/app/playground/PlaygroundClient.tsx
@@ -62,6 +62,7 @@ import {PreviewStage, type Viewport} from './PreviewStage';
import {BRAND_ICON} from '../../components/XDSWordmark';
import {PropertyPanel} from './PropertyPanel';
import {annotateInstanceIds} from './babelParser';
+import {trackCopy} from '../../lib/analytics';
import {PlaygroundThemeEditor} from '../../components/themePlayground/PlaygroundThemeEditor';
import {DEFAULT_CODE} from './defaultCode';
@@ -637,6 +638,7 @@ export function PlaygroundClient() {
const handleShare = useCallback(() => {
navigator.clipboard.writeText(window.location.href).then(() => {
+ trackCopy({page: 'playground', target: 'share_url'});
setCopied(true);
setTimeout(() => setCopied(false), 2000);
});
diff --git a/apps/docsite/src/components/SearchPalette.tsx b/apps/docsite/src/components/SearchPalette.tsx
index a59e7746f9..ce6f7b420a 100644
--- a/apps/docsite/src/components/SearchPalette.tsx
+++ b/apps/docsite/src/components/SearchPalette.tsx
@@ -17,6 +17,7 @@ interface SearchItem extends XDSSearchableItem<{group: string}> {
import type {PackageMeta} from '../generated/packageRegistry';
import type {DocTopic} from '../generated/docsRegistry';
import type {TemplateEntry} from '../generated/templateRegistry';
+import {trackSearch} from '../lib/analytics';
interface SearchPaletteProps {
isOpen: boolean;
@@ -104,6 +105,18 @@ export function SearchPalette({
const handleValueChange = useCallback(
(value: string) => {
if (value && value.startsWith('/')) {
+ // Determine type from path prefix
+ const type = value.startsWith('/components/')
+ ? 'component'
+ : value.startsWith('/templates/')
+ ? 'template'
+ : value.startsWith('/themes/')
+ ? 'theme'
+ : value.startsWith('/docs/')
+ ? 'doc'
+ : 'page';
+ const item = value.split('/').pop() || value;
+ trackSearch({target: 'select', item, type});
router.push(value);
onOpenChange(false);
}
diff --git a/apps/docsite/src/components/SharedTopNav.tsx b/apps/docsite/src/components/SharedTopNav.tsx
index 7328ff416d..3aa767c042 100644
--- a/apps/docsite/src/components/SharedTopNav.tsx
+++ b/apps/docsite/src/components/SharedTopNav.tsx
@@ -16,6 +16,7 @@ import {packages} from '../generated/packageRegistry';
import {docTopics} from '../generated/docsRegistry';
import {templates} from '../generated/templateRegistry';
import {useThemeMode} from '../app/providers';
+import {trackSearch, trackClickCta} from '../lib/analytics';
const GitHubIcon = ({
width = 20,
@@ -106,7 +107,10 @@ export function SharedTopNav() {
variant="ghost"
isIconOnly
icon={<Search size={20} />}
- onClick={() => setIsSearchOpen(true)}
+ onClick={() => {
+ trackSearch({target: 'open'});
+ setIsSearchOpen(true);
+ }}
/>
<XDSButton
label={
@@ -139,12 +143,16 @@ export function SharedTopNav() {
isIconOnly
icon={<GitHubIcon />}
href={GITHUB_REPO}
+ onClick={() => trackClickCta({target: 'github'})}
/>
</XDSHStack>
<XDSButton
label="Get started"
variant="primary"
href="/docs/getting-started"
+ onClick={() =>
+ trackClickCta({page: 'landing', target: 'get_started'})
+ }
/>
</XDSHStack>
}
diff --git a/apps/docsite/src/components/TemplatePreviewDialog.tsx b/apps/docsite/src/components/TemplatePreviewDialog.tsx
index f5760918eb..283ee849eb 100644
--- a/apps/docsite/src/components/TemplatePreviewDialog.tsx
+++ b/apps/docsite/src/components/TemplatePreviewDialog.tsx
@@ -41,6 +41,7 @@ import {XDSDialog} from '@xds/core/Dialog';
import {XDSTooltip} from '@xds/core/Tooltip';
import {TemplatePreviewSurface} from './TemplatePreviewSurface';
import {buildPlaygroundHref} from './playgroundLink';
+import {trackCopy, trackOpenPlayground, trackNavigate} from '../lib/analytics';
export interface TemplatePreviewItem {
slug: string;
@@ -166,8 +167,15 @@ export function TemplatePreviewDialog({
if (count === 0) {
return;
}
+ const nextIndex = (index + delta + count) % count;
+ trackNavigate({
+ page: 'templates',
+ target: 'prev_next',
+ direction: delta > 0 ? 'next' : 'prev',
+ item: items[nextIndex]?.slug,
+ });
startTransition(() => {
- onIndexChange((index + delta + count) % count);
+ onIndexChange(nextIndex);
});
};
@@ -206,9 +214,15 @@ export function TemplatePreviewDialog({
const handleCopyCmd = useCallback(() => {
navigator.clipboard.writeText(useCommand).then(() => {
setCmdCopied(true);
+ trackCopy({
+ page: 'templates',
+ target: 'cli_command',
+ item: current.slug,
+ category: current.category,
+ });
setTimeout(() => setCmdCopied(false), 2000);
});
- }, [useCommand]);
+ }, [useCommand, current.slug, current.category]);
return (
<XDSDialog
@@ -259,6 +273,11 @@ export function TemplatePreviewDialog({
variant="primary"
size="lg"
onClick={() => {
+ trackOpenPlayground({
+ page: 'templates',
+ item: current.slug,
+ category: current.category,
+ });
window.location.href =
buildPlaygroundHref(playgroundSource);
}}
diff --git a/apps/docsite/src/components/ThemePackagePage.tsx b/apps/docsite/src/components/ThemePackagePage.tsx
index 3e7254fb4a..1369a344ad 100644
--- a/apps/docsite/src/components/ThemePackagePage.tsx
+++ b/apps/docsite/src/components/ThemePackagePage.tsx
@@ -23,6 +23,7 @@ import {ThemeCardShowcase} from './ThemeCardShowcase';
import {getThemeImages} from './themeImages';
import {packages} from '../generated/packageRegistry';
import {themeObjects} from '../generated/themeRegistry';
+import {trackClickCta, trackToggle} from '../lib/analytics';
// Gallery order — themes are listed in the same canonical visual-
// closeness order used elsewhere (most restrained → most expressive).
@@ -599,6 +600,11 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
return;
}
event.preventDefault();
+ trackClickCta({
+ page: 'themes',
+ target: 'customize',
+ item: selectedPkgName,
+ });
setIsLeaving(true);
// Wait for the leave animation to play, then navigate. Length
// matches --duration-medium (~410ms); we use a slight buffer
@@ -669,7 +675,16 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
label={modeToggleLabel}
tooltip={modeToggleLabel}
icon={modeToggleIcon}
- onClick={() => setMode(mode === 'light' ? 'dark' : 'light')}
+ onClick={() => {
+ const next = mode === 'light' ? 'dark' : 'light';
+ trackToggle({
+ page: 'themes',
+ target: 'mode',
+ item: selectedPkgName,
+ value: next,
+ });
+ setMode(next);
+ }}
/>
</XDSHStack>
</XDSVStack>
diff --git a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
index b145eb1295..6b06e7ee33 100644
--- a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
+++ b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
@@ -27,6 +27,7 @@ import type {BlockEntry} from '../../generated/blockRegistry';
import {showcaseRegistry} from '../../generated/showcaseRegistry';
import {exampleRegistry} from '../../generated/exampleRegistry';
import {spacingVars} from '@xds/core/theme/tokens.stylex';
+import {trackNavigate} from '../../lib/analytics';
const styles = stylex.create({
section: {
@@ -125,6 +126,12 @@ function ComponentDetailInner({
const tab = searchParams.get('tab') ?? 'overview';
const setTab = (value: string) => {
+ trackNavigate({
+ page: 'components',
+ target: 'tab',
+ tab: value,
+ item: comp.name,
+ });
const params = new URLSearchParams(searchParams.toString());
if (value === 'overview') {
params.delete('tab');
diff --git a/apps/docsite/src/components/component-detail/ExampleBlock.tsx b/apps/docsite/src/components/component-detail/ExampleBlock.tsx
index 082adbb595..c1226919e6 100644
--- a/apps/docsite/src/components/component-detail/ExampleBlock.tsx
+++ b/apps/docsite/src/components/component-detail/ExampleBlock.tsx
@@ -17,6 +17,7 @@ import {neutralTheme} from '@xds/theme-neutral/built';
import {useThemeMode} from '../../app/providers';
import type {ExampleEntry} from '../../generated/exampleRegistry';
import {buildPlaygroundHref} from '../playgroundLink';
+import {trackOpenPlayground} from '../../lib/analytics';
function LivePreview({entry}: {entry: ExampleEntry}) {
const {mode} = useThemeMode();
@@ -96,6 +97,7 @@ export function ExampleBlock({entry}: ExampleBlockProps) {
variant="ghost"
size="sm"
onClick={() => {
+ trackOpenPlayground({page: 'components', item: entry.name});
window.location.href = buildPlaygroundHref(entry.source);
}}
/>
diff --git a/apps/docsite/src/components/themePlayground/ThemeEditorView.tsx b/apps/docsite/src/components/themePlayground/ThemeEditorView.tsx
index 39dbd8a23d..384afe9ff6 100644
--- a/apps/docsite/src/components/themePlayground/ThemeEditorView.tsx
+++ b/apps/docsite/src/components/themePlayground/ThemeEditorView.tsx
@@ -60,6 +60,7 @@ import {
} from './helpers';
import {getThemeList} from './themeList';
import type {ThemeListEntry} from './themeList';
+import {trackExport} from '../../lib/analytics';
const ALL_DEFAULTS: Record<string, string> = {
...colorDefaults,
@@ -645,7 +646,10 @@ export function ThemeEditorView({
label="Export Theme"
variant="secondary"
size="md"
- onClick={() => setShowExportDialog(true)}
+ onClick={() => {
+ trackExport({page: 'themes', item: selectedThemeId});
+ setShowExportDialog(true);
+ }}
/>
</XDSHStack>
</div>
diff --git a/apps/docsite/src/lib/analytics.ts b/apps/docsite/src/lib/analytics.ts
new file mode 100644
index 0000000000..a82ea2a0ea
--- /dev/null
+++ b/apps/docsite/src/lib/analytics.ts
@@ -0,0 +1,116 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file analytics.ts
+ * @position src/lib — typed analytics helpers wrapping @vercel/analytics.
+ *
+ * Convention: small fixed set of event names, context pushed into properties.
+ * See https://github.com/facebookexperimental/xds/issues/2607 for the full spec.
+ */
+
+import {track} from '@vercel/analytics';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type Page =
+ | 'templates'
+ | 'themes'
+ | 'components'
+ | 'playground'
+ | 'docs'
+ | 'landing';
+
+type CopyTarget =
+ | 'cli_command'
+ | 'import_path'
+ | 'code_block'
+ | 'share_url'
+ | 'install_command';
+
+type CtaTarget = 'install' | 'get_started' | 'github' | 'community';
+
+type NavigateTarget = 'prev_next' | 'tab' | 'view';
+
+type ToggleTarget = 'mode' | 'viewport';
+
+interface BaseProps {
+ page?: Page;
+ item?: string;
+ category?: string;
+}
+
+/** Collapse typed props into a plain Record that track() accepts. */
+function props(obj: object): Record<string, string | number | boolean> {
+ const out: Record<string, string | number | boolean> = {};
+ for (const [k, v] of Object.entries(obj)) {
+ if (v !== undefined) {
+ out[k] = v;
+ }
+ }
+ return out;
+}
+
+// ---------------------------------------------------------------------------
+// Event helpers
+// ---------------------------------------------------------------------------
+
+/** Something was viewed (dialog opened, detail page loaded). */
+export function trackView(
+ p: BaseProps & {package?: string; has_shared_code?: boolean},
+) {
+ track('view', props(p));
+}
+
+/** User copied something to clipboard. */
+export function trackCopy(
+ p: BaseProps & {target: CopyTarget; example?: string},
+) {
+ track('copy', props(p));
+}
+
+/** Navigated to playground with code. */
+export function trackOpenPlayground(
+ p: BaseProps & {example?: string; source?: string},
+) {
+ track('open_playground', props(p));
+}
+
+/** Moved between items (prev/next, tab switch). */
+export function trackNavigate(
+ p: BaseProps & {
+ target: NavigateTarget;
+ direction?: 'next' | 'prev';
+ tab?: string;
+ view?: string;
+ },
+) {
+ track('navigate', props(p));
+}
+
+/** Search palette interaction. */
+export function trackSearch(p: {
+ target: 'open' | 'select';
+ item?: string;
+ type?: string;
+}) {
+ track('search', props(p));
+}
+
+/** CTA button clicked. */
+export function trackClickCta(p: BaseProps & {target: CtaTarget}) {
+ track('click_cta', props(p));
+}
+
+/** Mode/setting toggled. */
+export function trackToggle(
+ p: BaseProps & {target: ToggleTarget; value: string},
+) {
+ track('toggle', props(p));
+}
+
+/** Theme exported. */
+export function trackExport(p: BaseProps) {
+ track('export', props(p));
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a1f82989f6..574dd9092a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -106,6 +106,9 @@ importers:
'@stylexjs/stylex':
specifier: ^0.18.3
version: 0.18.3
+ '@vercel/analytics':
+ specifier: ^2.0.1
'@xds/cli':
specifier: '*'
version: link:../../packages/cli
@@ -3719,6 +3722,35 @@ packages:
resolution: {integrity: sha512-9WI52t8ZGLVGrPMBet25yAftqY/n95+zmoUUtJBBQTKDSKUu7OsPTroT2op7U9JatkoRccL0YkWDNMFfC4Sjxg==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+ '@vercel/[email protected]':
+ resolution: {integrity: sha512-MTQG6V9qQrt1tsDeF+2Uoo5aPjqbVPys1xvnIftXSJYG2SrwXRHnqEvVoYID7BTruDz4lCd2Z7rM1BdkUehk2g==}
+ peerDependencies:
+ '@remix-run/react': ^2
+ '@sveltejs/kit': ^1 || ^2
+ next: '>= 13'
+ nuxt: '>= 3'
+ react: ^18 || ^19 || ^19.0.0-rc
+ svelte: '>= 4'
+ vue: ^3
+ vue-router: ^4
+ peerDependenciesMeta:
+ '@remix-run/react':
+ optional: true
+ '@sveltejs/kit':
+ optional: true
+ next:
+ optional: true
+ nuxt:
+ optional: true
+ react:
+ optional: true
+ svelte:
+ optional: true
+ vue:
+ optional: true
+ vue-router:
+ optional: true
+
'@vitejs/[email protected]':
resolution: {integrity: sha512-gUu9hwfWvvEDBBmgtAowQCojwZmJ5mcLn3aufeCsitijs3+f2NsrPtlAWIR6OPiqljl96GVCUbLe0HyqIpVaoA==}
engines: {node: ^14.18.0 || >=16.0.0}
@@ -8942,6 +8974,11 @@ snapshots:
'@typescript-eslint/types': 8.60.0
eslint-visitor-keys: 5.0.1
+ optionalDependencies:
+ react: 19.2.7
+
dependencies:
'@babel/core': 7.29.0