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.jsonindex 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.tsxindex 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 forthe action buttons so each keeps its ownbehavior (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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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"isIconOnlyicon={<Search size={20} />}- onClick={() => setIsSearchOpen(true)}+ onClick={() => {+ trackSearch({target: 'open'});+ setIsSearchOpen(true);+ }}/><XDSButtonlabel={@@ -139,12 +143,16 @@ export function SharedTopNav() {isIconOnlyicon={<GitHubIcon />}href={GITHUB_REPO}+ onClick={() => trackClickCta({target: 'github'})}/></XDSHStack><XDSButtonlabel="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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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.yamlindex a1f82989f6..574dd9092a 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -106,6 +106,9 @@ importers:'@stylexjs/stylex':specifier: ^0.18.3version: 0.18.3+ '@vercel/analytics':+ specifier: ^2.0.1+ version: 2.0.1([email protected](@babel/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected]))([email protected])'@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.0eslint-visitor-keys: 5.0.1+ '@vercel/[email protected]([email protected](@babel/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected]))([email protected])':+ optionalDependencies:+ next: 15.5.18(@babel/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])+ react: 19.2.7+'@vitejs/[email protected]([email protected](@types/[email protected])([email protected])([email protected])([email protected]))':dependencies:'@babel/core': 7.29.0