feat: add analytics support with use-analytics (#90)

Author: rsbh

bun.lock

@@ -36,6 +36,7 @@
     "typescript": "5.9.3"
   },
   "dependencies": {
+    "@analytics/google-analytics": "^1.1.0",
     "@codemirror/lang-json": "^6.0.2",
     "@codemirror/state": "^6.5.4",
     "@codemirror/theme-one-dark": "^6.1.3",
@@ -51,6 +52,7 @@
     "@shikijs/rehype": "^4.0.2",
     "@tanstack/react-query": "5.100.10",
     "@vitejs/plugin-react": "^6.0.1",
+    "analytics": "^0.8.19",
     "chalk": "^5.6.2",
     "class-variance-authority": "^0.7.1",
     "codemirror": "^6.0.2",
@@ -79,6 +81,7 @@
     "std-env": "^4.1.0",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
+    "use-analytics": "^1.1.0",
     "vite": "8.0.3",
     "yaml": "^2.8.2",
     "zod": "^4.3.6"

packages/chronicle/package.json

@@ -0,0 +1,64 @@
+import { useEffect, useState } from 'react'
+import { useLocation } from 'react-router'
+import type { ReactNode } from 'react'
+import type { AnalyticsConfig } from '@/types'
+import type { AnalyticsInstance } from 'analytics'
+
+function PageViewTracker({ analytics }: { analytics: AnalyticsInstance }) {
+  const { pathname } = useLocation()
+
+  useEffect(() => {
+    try { analytics.page() } catch { /* noop */ }
+  }, [pathname, analytics])
+
+  return null
+}
+
+export function AnalyticsProvider({
+  config,
+  appName,
+  children,
+}: {
+  config: AnalyticsConfig
+  appName: string
+  children: ReactNode
+}) {
+  const [analytics, setAnalytics] = useState<AnalyticsInstance | null>(null)
+
+  useEffect(() => {
+    if (!config.enabled) {
+      setAnalytics(null)
+      return
+    }
+
+    let cancelled = false
+
+    const init = async () => {
+      try {
+        const plugins: unknown[] = []
+        if (config.googleAnalytics?.measurementId) {
+          const { default: googleAnalytics } = await import('@analytics/google-analytics')
+          plugins.push(
+            googleAnalytics({
+              measurementIds: [config.googleAnalytics.measurementId],
+            })
+          )
+        }
+        const { default: Analytics } = await import('analytics')
+        if (!cancelled) setAnalytics(Analytics({ app: appName, plugins }))
+      } catch {
+        if (!cancelled) setAnalytics(null)
+      }
+    }
+
+    void init()
+    return () => { cancelled = true }
+  }, [config.enabled, config.googleAnalytics?.measurementId, appName])
+
+  return (
+    <>
+      {analytics && <PageViewTracker analytics={analytics} />}
+      {children}
+    </>
+  )
+}

packages/chronicle/src/components/analytics/AnalyticsProvider.tsx

@@ -3,6 +3,7 @@ import '@raystack/apsara/style.css';
 import { ThemeProvider, Skeleton, Flex } from '@raystack/apsara';
 import { lazy, Suspense } from 'react';
 import { Navigate, useLocation } from 'react-router';
+import { AnalyticsProvider } from '@/components/analytics/AnalyticsProvider';
 import { Head } from '@/lib/head';
 import { usePageContext } from '@/lib/page-context';
 import { resolveRoute, RouteType } from '@/lib/route-resolver';
@@ -37,18 +38,20 @@ export function App() {
       enableSystem={themeConfig.enableSystem}
       forcedTheme={themeConfig.forcedTheme}
     >
-      <RootHead config={config} />
-      <Suspense fallback={<PageFallback />}>
-        {isApi ? (
-          <ApiLayout>
-            <ApiPage slug={apiSlug} />
-          </ApiLayout>
-        ) : (
-          <DocsLayout hideSidebar={isLanding}>
-            {isLanding ? <LandingPage /> : <DocsPage slug={docsSlug} />}
-          </DocsLayout>
-        )}
-      </Suspense>
+      <AnalyticsProvider config={config.analytics ?? { enabled: false }} appName={config.site.title}>
+        <RootHead config={config} />
+        <Suspense fallback={<PageFallback />}>
+          {isApi ? (
+            <ApiLayout>
+              <ApiPage slug={apiSlug} />
+            </ApiLayout>
+          ) : (
+            <DocsLayout hideSidebar={isLanding}>
+              {isLanding ? <LandingPage /> : <DocsPage slug={docsSlug} />}
+            </DocsLayout>
+          )}
+        </Suspense>
+      </AnalyticsProvider>
     </ThemeProvider>
   );
 }

packages/chronicle/src/server/App.tsx

@@ -132,7 +132,8 @@ export async function createViteConfig(
       }
     },
     ssr: {
-      noExternal: ['@raystack/apsara', 'dayjs', 'fumadocs-core']
+      noExternal: ['@raystack/apsara', 'dayjs', 'fumadocs-core'],
+      external: ['analytics', 'use-analytics', '@analytics/google-analytics'],
     },
     environments: {
       client: {