perf: improve docs mobile performance

package.json

@@ -47,7 +47,7 @@
     "unplugin-auto-import": "^21.0.0",
     "unplugin-icons": "^23.0.1",
     "viem": "^2.48.8",
-    "vocs": "2.0.0-rc.0",
+    "vocs": "2.0.0-rc.2",
     "wagmi": "3.6.14",
     "waku": "1.0.0-beta.0",
     "webauthx": "~0.1.1",

src/components/PostHogSetup.tsx

@@ -1,6 +1,5 @@
 'use client'
 
-import posthog from 'posthog-js'
 import { useEffect } from 'react'
 
 function PostHogInitializer() {
@@ -10,7 +9,9 @@ function PostHogInitializer() {
 
     if (!posthogKey || !posthogHost) return
 
-    const init = () => {
+    const init = async () => {
+      const { default: posthog } = await import('posthog-js')
+
       posthog.init(posthogKey, {
         api_host: '/ingest',
         ui_host: posthogHost,
@@ -28,10 +29,12 @@ function PostHogInitializer() {
     }
 
     if ('requestIdleCallback' in window) {
-      window.requestIdleCallback(init)
-    } else {
-      setTimeout(init, 1)
+      const idleId = window.requestIdleCallback(init, { timeout: 2_000 })
+      return () => window.cancelIdleCallback(idleId)
     }
+
+    const timeoutId = globalThis.setTimeout(init, 1)
+    return () => globalThis.clearTimeout(timeoutId)
   }, [])
 
   return null

src/lib/pageSettled.ts

@@ -0,0 +1,44 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+const pageSettledDelayMs = 4_000
+
+export function onPageSettled(callback: () => void) {
+  if (typeof window === 'undefined') return () => {}
+
+  let cancelled = false
+  let timeoutId: number | undefined
+  let idleId: number | undefined
+
+  const run = () => {
+    if (cancelled) return
+    if ('requestIdleCallback' in window) {
+      idleId = window.requestIdleCallback(callback, { timeout: 2_000 })
+      return
+    }
+    callback()
+  }
+
+  const schedule = () => {
+    timeoutId = window.setTimeout(run, pageSettledDelayMs)
+  }
+
+  if (document.readyState === 'complete') schedule()
+  else window.addEventListener('load', schedule, { once: true })
+
+  return () => {
+    cancelled = true
+    window.removeEventListener('load', schedule)
+    if (timeoutId) window.clearTimeout(timeoutId)
+    if (idleId && 'cancelIdleCallback' in window) window.cancelIdleCallback(idleId)
+  }
+}
+
+export function usePageSettled() {
+  const [settled, setSettled] = useState(false)
+
+  useEffect(() => onPageSettled(() => setSettled(true)), [])
+
+  return settled
+}

src/lib/useRootWebAuthnAccount.ts

@@ -3,8 +3,8 @@
 import { useQuery } from '@tanstack/react-query'
 import type { WebAuthnP256 } from 'viem/tempo'
 import { Account } from 'viem/tempo'
-import { useConnection } from 'wagmi'
-import { config, webAuthnRpId } from '../wagmi.config.ts'
+import { useConfig, useConnection } from 'wagmi'
+import { webAuthnRpId } from '../wagmi.config.ts'
 
 type RootWebAuthnAccount = ReturnType<typeof Account.fromWebAuthnP256>
 type RootWebAuthnCredential = WebAuthnP256.P256Credential
@@ -20,6 +20,7 @@ type RootWebAuthnAccountProvider = {
 const rootWebAuthnAccountTimeoutMs = 30_000
 
 export function useRootWebAuthnAccount() {
+  const config = useConfig()
   const { address, connector } = useConnection()
 
   return useQuery({
@@ -45,6 +46,7 @@ export function useRootWebAuthnAccount() {
       }
 
       const credential = await waitForStoredCredential(
+        config,
         address as `0x${string}`,
         rootWebAuthnAccountTimeoutMs,
       )
@@ -92,6 +94,7 @@ async function waitForProviderAccount(
 }
 
 async function waitForStoredCredential(
+  config: ReturnType<typeof useConfig>,
   address: `0x${string}`,
   timeoutMs = 5_000,
 ): Promise<RootWebAuthnCredential> {

src/pages/_layout.tsx

@@ -1,11 +1,17 @@
 'use client'
 
-import { Analytics } from '@vercel/analytics/react'
-import { SpeedInsights } from '@vercel/speed-insights/react'
-import type React from 'react'
-import { Toaster } from 'sonner'
-import GoogleAnalytics from '../components/GoogleAnalytics'
-import PostHogSetup from '../components/PostHogSetup'
+import { lazy, type PropsWithChildren, Suspense } from 'react'
+import { usePageSettled } from '../lib/pageSettled'
+
+const Analytics = lazy(() =>
+  import('@vercel/analytics/react').then((module) => ({ default: module.Analytics })),
+)
+const SpeedInsights = lazy(() =>
+  import('@vercel/speed-insights/react').then((module) => ({ default: module.SpeedInsights })),
+)
+const Toaster = lazy(() => import('sonner').then((module) => ({ default: module.Toaster })))
+const GoogleAnalytics = lazy(() => import('../components/GoogleAnalytics'))
+const PostHogSetup = lazy(() => import('../components/PostHogSetup'))
 
 if (typeof window !== 'undefined') {
   window.addEventListener('vite:preloadError', (event) => {
@@ -18,30 +24,41 @@ if (typeof window !== 'undefined') {
 }
 
 export default function Layout(
-  props: React.PropsWithChildren<{
+  props: PropsWithChildren<{
     path: string
-    frontmatter?: { mipd?: boolean }
+    frontmatter?: { interactive?: boolean; mipd?: boolean }
   }>,
 ) {
+  const pageSettled = usePageSettled()
+  const needsToaster = Boolean(props.frontmatter?.interactive || props.frontmatter?.mipd)
+
   return (
     <>
       {props.children}
-      <Toaster
-        className="z-42069 select-none"
-        expand={false}
-        position="bottom-right"
-        swipeDirections={['right', 'left', 'top', 'bottom']}
-        theme="light"
-        toastOptions={{
-          style: {
-            borderRadius: '1.5rem',
-          },
-        }}
-      />
-      <SpeedInsights route={props.path} />
-      <Analytics />
-      <GoogleAnalytics />
-      <PostHogSetup />
+      <Suspense fallback={null}>
+        {needsToaster && (
+          <Toaster
+            className="z-42069 select-none"
+            expand={false}
+            position="bottom-right"
+            swipeDirections={['right', 'left', 'top', 'bottom']}
+            theme="light"
+            toastOptions={{
+              style: {
+                borderRadius: '1.5rem',
+              },
+            }}
+          />
+        )}
+        {pageSettled && (
+          <>
+            <SpeedInsights route={props.path} />
+            <Analytics />
+            <GoogleAnalytics />
+            <PostHogSetup />
+          </>
+        )}
+      </Suspense>
     </>
   )
 }

src/pages/_mdx-wrapper.tsx

@@ -1,7 +1,7 @@
 'use client'
 
 /**
- * MDX page wrapper — wraps every MDX page rendered by Vocs.
+ * MDX page wrapper: wraps every MDX page rendered by Vocs.
  *
  * ## Conditional Providers
  *
@@ -20,26 +20,29 @@
  *
  * ## Frontmatter flags
  *
- * - `interactive` — loads the Wagmi/QueryClient provider tree. Required for
+ * - `interactive` loads the Wagmi/QueryClient provider tree. Required for
  *   any page that uses wallet hooks, Demo components, or guide steps.
- * - `mipd` — enables Multi Injected Provider Discovery (auto-detects browser
+ * - `mipd` enables Multi Injected Provider Discovery (auto-detects browser
  *   extension wallets like MetaMask). Implies `interactive`. Only needed on
  *   pages where users connect external wallets.
  */
 
-import type React from 'react'
+import { lazy, type ReactNode, Suspense } from 'react'
 import { Layout, MdxPageContext } from 'vocs'
-import Providers from '../components/Providers'
 
-export default function MDXWrapper({ children }: { children: React.ReactNode }) {
+const Providers = lazy(() => import('../components/Providers'))
+
+export default function MDXWrapper({ children }: { children: ReactNode }) {
   const context = MdxPageContext.use()
   const frontmatter = context.frontmatter as Record<string, unknown> | undefined
   const needsProviders = Boolean(frontmatter?.interactive || frontmatter?.mipd)
 
   return (
     <Layout>
       {needsProviders ? (
-        <Providers mipd={frontmatter?.mipd as boolean | undefined}>{children}</Providers>
+        <Suspense fallback={null}>
+          <Providers mipd={frontmatter?.mipd as boolean | undefined}>{children}</Providers>
+        </Suspense>
       ) : (
         children
       )}

src/pages/index.mdx

@@ -35,7 +35,7 @@ These docs cover everything from creating a wallet to building payment systems o
   />
   <Card
     title="Make Agentic Payments"
-    description="Let agents pay for services using the Machine Payments Protocol — sessions and streaming payments."
+    description="Let agents pay for services using the Machine Payments Protocol - sessions and streaming payments."
     to="/guide/machine-payments"
     icon="lucide:bot"
   />

src/wagmi.config.ts

@@ -109,8 +109,6 @@ export namespace getConfig {
 
 export type Config = ReturnType<typeof getConfig>
 
-export const config = getConfig()
-
 export const queryClient = new QueryClient()
 
 export function useTempoWalletConnector() {