Loading documentation...
Preparing Ring content
Concepts, value, and typical clone scenarios — less code.
Concepts, value, and typical clone scenarios — less code.
Preparing Ring content
Preparing Ring content
Preparing Ring content
Filter with Founder / Developer in the docs sidebar. This page replaces legacy fiction ($2.8M revenue, invented dashboard examples, fake Lighthouse SLAs). Patterns below are traced to next.config.mjs, lib/cached-data.ts, components/providers/web-vitals-provider.tsx, features/analytics/lib/analytics-db.ts, and production Docker lessons.
Ring Platform targets fast first paint (React 19 Server Components by default), fresh marketplace lists (cache tags + mutation sync), and measurable UX (Core Web Vitals ingest). Performance is a deploy concern — build timeouts, SSR traps, and cache invalidation — not only frontend polish.
| Layer | Mechanism | Where |
|---|---|---|
| Framework | Next.js 16 App Router, cacheComponents: true | next.config.mjs |
| List caching | unstable_cache + revalidateTag | lib/cached-data.ts |
| Request dedup | React.cache() on server reads | lib/services/firebase-service-manager.ts, actions |
| Post-write reads | 30s in-process entity cache | DatabaseService EntityCache |
| Heavy client UI | dynamic(..., { ssr: false }) | components/docs/mdx-heavy-components.tsx |
| Docs code blocks | Server Shiki (highlightCodeToHtml) | components/docs/code.tsx |
| Images | next/image WebP/AVIF | next.config.mjs → images.formats |
| UX metrics | useReportWebVitals → POST /api/analytics/web-vitals | components/providers/web-vitals-provider.tsx, features/analytics/lib/analytics-db.ts |
| Resource hints | prefetchDNS / preinit scripts | contexts/app-context.tsx |
Slow opportunity and store pages directly hit conversion: members abandon checkout, vendors see empty dashboards, and AI matcher notifications feel “late” even when data is correct.
Admin → Analytics shows Web Vitals medians and client errors — establish a baseline before rebranding or adding heavy hero media.
Product and entity images should use Blob/CDN URLs via next/image — oversized PNG heroes are the most common LCP regression on new clones.
After vendors post listings, caches must invalidate — if lists look stale, fix sync before scaling servers.
Next-step: health checks, the Web Vitals API, and the admin analytics dashboard.
Same-workflow: Mermaid SSR incident history and health probes.
Deep-dive: cache invalidation after entity/opportunity CRUD.
See-also: implementation patterns for cache(), static generation, and edge notes.
Filter with Founder / Developer in the docs sidebar. This page replaces legacy fiction ($2.8M revenue, invented dashboard examples, fake Lighthouse SLAs). Patterns below are traced to next.config.mjs, lib/cached-data.ts, components/providers/web-vitals-provider.tsx, features/analytics/lib/analytics-db.ts, and production Docker lessons.
Ring Platform targets fast first paint (React 19 Server Components by default), fresh marketplace lists (cache tags + mutation sync), and measurable UX (Core Web Vitals ingest). Performance is a deploy concern — build timeouts, SSR traps, and cache invalidation — not only frontend polish.
| Layer | Mechanism | Where |
|---|---|---|
| Framework | Next.js 16 App Router, cacheComponents: true | next.config.mjs |
| List caching | unstable_cache + revalidateTag | lib/cached-data.ts |
| Request dedup | React.cache() on server reads | lib/services/firebase-service-manager.ts, actions |
| Post-write reads | 30s in-process entity cache | DatabaseService EntityCache |
| Heavy client UI | dynamic(..., { ssr: false }) | components/docs/mdx-heavy-components.tsx |
| Docs code blocks | Server Shiki (highlightCodeToHtml) | components/docs/code.tsx |
| Images | next/image WebP/AVIF | next.config.mjs → images.formats |
| UX metrics | useReportWebVitals → POST /api/analytics/web-vitals | components/providers/web-vitals-provider.tsx, features/analytics/lib/analytics-db.ts |
| Resource hints | prefetchDNS / preinit scripts | contexts/app-context.tsx |
Slow opportunity and store pages directly hit conversion: members abandon checkout, vendors see empty dashboards, and AI matcher notifications feel “late” even when data is correct.
Admin → Analytics shows Web Vitals medians and client errors — establish a baseline before rebranding or adding heavy hero media.
Product and entity images should use Blob/CDN URLs via next/image — oversized PNG heroes are the most common LCP regression on new clones.
After vendors post listings, caches must invalidate — if lists look stale, fix sync before scaling servers.
Next-step: health checks, the Web Vitals API, and the admin analytics dashboard.
Same-workflow: Mermaid SSR incident history and health probes.
Deep-dive: cache invalidation after entity/opportunity CRUD.
See-also: implementation patterns for cache(), static generation, and edge notes.
Filter with Founder / Developer in the docs sidebar. This page replaces legacy fiction ($2.8M revenue, invented dashboard examples, fake Lighthouse SLAs). Patterns below are traced to next.config.mjs, lib/cached-data.ts, components/providers/web-vitals-provider.tsx, features/analytics/lib/analytics-db.ts, and production Docker lessons.
Ring Platform targets fast first paint (React 19 Server Components by default), fresh marketplace lists (cache tags + mutation sync), and measurable UX (Core Web Vitals ingest). Performance is a deploy concern — build timeouts, SSR traps, and cache invalidation — not only frontend polish.
| Layer | Mechanism | Where |
|---|---|---|
| Framework | Next.js 16 App Router, cacheComponents: true | next.config.mjs |
| List caching | unstable_cache + revalidateTag | lib/cached-data.ts |
| Request dedup | React.cache() on server reads | lib/services/firebase-service-manager.ts, actions |
| Post-write reads | 30s in-process entity cache | DatabaseService EntityCache |
| Heavy client UI | dynamic(..., { ssr: false }) | components/docs/mdx-heavy-components.tsx |
| Docs code blocks | Server Shiki (highlightCodeToHtml) | components/docs/code.tsx |
| Images | next/image WebP/AVIF | next.config.mjs → images.formats |
| UX metrics | useReportWebVitals → POST /api/analytics/web-vitals | components/providers/web-vitals-provider.tsx, features/analytics/lib/analytics-db.ts |
| Resource hints | prefetchDNS / preinit scripts | contexts/app-context.tsx |
Slow opportunity and store pages directly hit conversion: members abandon checkout, vendors see empty dashboards, and AI matcher notifications feel “late” even when data is correct.
Admin → Analytics shows Web Vitals medians and client errors — establish a baseline before rebranding or adding heavy hero media.
Product and entity images should use Blob/CDN URLs via next/image — oversized PNG heroes are the most common LCP regression on new clones.
After vendors post listings, caches must invalidate — if lists look stale, fix sync before scaling servers.
Next-step: health checks, the Web Vitals API, and the admin analytics dashboard.
Same-workflow: Mermaid SSR incident history and health probes.
Deep-dive: cache invalidation after entity/opportunity CRUD.
See-also: implementation patterns for cache(), static generation, and edge notes.
| Metric | Good (≤) | Poor (>) |
|---|---|---|
| LCP | 2.5s | 4s |
| INP | 200ms | 500ms |
| CLS | 0.1 | 0.25 |
| TTFB | 800ms | 1.8s |
| FCP | 1.8s | 3s |
| FID | 100ms | 300ms |
Thresholds come from ratingForMetric in features/analytics/lib/analytics-db.ts. The client reports each metric's rating from next/web-vitals and buffers them into one POST per debounce window to /api/analytics/web-vitals.
Treat performance as release criteria for major clone launches: run Lighthouse on /, /opportunities, and /store after deploy — compare with Admin analytics the following week.
useActionStatefeatures/reviews/components/review-form.tsx |
useOptimistic | hooks/use-realtime.ts, hooks/use-realtime-opportunities.ts |
Server Actions + revalidatePath | app/_actions/*.ts |
Prefer Server Components for list/detail shells; isolate 'use client' to forms, tunnel, wallet, and viz widgets.
Docs and marketing widgets load via dynamic(..., { ssr: false }) in mdx-heavy-components.tsx. Top-level Mermaid/Shiki on the server caused 30s loads and 503s in production — see Docker deployment.
<Code> is async server Shikicomponents/docs/code.tsx calls highlightCodeToHtml once per block — do not add client-side highlighters on the same page.
staticPageGenerationTimeout: 180 in next.config.mjs — large doc trees or many locales need incremental static generation discipline; trim scanDocsStaticParams scope if builds exceed CI limits.
next.config.mjs sets output: 'standalone' with outputFileTracingRoot, serverExternalPackages (Firebase, Auth.js, Solana, nodemailer), and outputFileTracingIncludes (i18n, locales, docs, ring-config, server.ts) so container images trace only the server bundles they need.
next.config.mjs enables WebP/AVIF (images.formats) and remote patterns for Google avatars, Google Fonts, Vercel Blob, and cdn.ring-platform.org — plus per-clone patterns via collectCloneImageRemotePatterns. Add new CDN hostnames to images.remotePatterns when onboarding a clone.
WebVitalsProvider (components/providers/web-vitals-provider.tsx), rendered in app-client-shell.tsx017_ring_analytics_schema.sqlGET /api/analytics/web-vitals?scope=platform (admin)ANALYTICS_DISABLE_STORAGE=true for load testsFull monitoring reference: Monitoring & analytics.
Implementation patterns (Firebase cache(), static generation, edge notes) live in Development: Performance and Features: Performance patterns — verify examples against postgres-primary clones before copying Firebase-specific snippets.
| Metric | Good (≤) | Poor (>) |
|---|---|---|
| LCP | 2.5s | 4s |
| INP | 200ms | 500ms |
| CLS | 0.1 | 0.25 |
| TTFB | 800ms | 1.8s |
| FCP | 1.8s | 3s |
| FID | 100ms | 300ms |
Thresholds come from ratingForMetric in features/analytics/lib/analytics-db.ts. The client reports each metric's rating from next/web-vitals and buffers them into one POST per debounce window to /api/analytics/web-vitals.
Treat performance as release criteria for major clone launches: run Lighthouse on /, /opportunities, and /store after deploy — compare with Admin analytics the following week.
useActionStatefeatures/reviews/components/review-form.tsx |
useOptimistic | hooks/use-realtime.ts, hooks/use-realtime-opportunities.ts |
Server Actions + revalidatePath | app/_actions/*.ts |
Prefer Server Components for list/detail shells; isolate 'use client' to forms, tunnel, wallet, and viz widgets.
Docs and marketing widgets load via dynamic(..., { ssr: false }) in mdx-heavy-components.tsx. Top-level Mermaid/Shiki on the server caused 30s loads and 503s in production — see Docker deployment.
<Code> is async server Shikicomponents/docs/code.tsx calls highlightCodeToHtml once per block — do not add client-side highlighters on the same page.
staticPageGenerationTimeout: 180 in next.config.mjs — large doc trees or many locales need incremental static generation discipline; trim scanDocsStaticParams scope if builds exceed CI limits.
next.config.mjs sets output: 'standalone' with outputFileTracingRoot, serverExternalPackages (Firebase, Auth.js, Solana, nodemailer), and outputFileTracingIncludes (i18n, locales, docs, ring-config, server.ts) so container images trace only the server bundles they need.
next.config.mjs enables WebP/AVIF (images.formats) and remote patterns for Google avatars, Google Fonts, Vercel Blob, and cdn.ring-platform.org — plus per-clone patterns via collectCloneImageRemotePatterns. Add new CDN hostnames to images.remotePatterns when onboarding a clone.
WebVitalsProvider (components/providers/web-vitals-provider.tsx), rendered in app-client-shell.tsx017_ring_analytics_schema.sqlGET /api/analytics/web-vitals?scope=platform (admin)ANALYTICS_DISABLE_STORAGE=true for load testsFull monitoring reference: Monitoring & analytics.
Implementation patterns (Firebase cache(), static generation, edge notes) live in Development: Performance and Features: Performance patterns — verify examples against postgres-primary clones before copying Firebase-specific snippets.
| Metric | Good (≤) | Poor (>) |
|---|---|---|
| LCP | 2.5s | 4s |
| INP | 200ms | 500ms |
| CLS | 0.1 | 0.25 |
| TTFB | 800ms | 1.8s |
| FCP | 1.8s | 3s |
| FID | 100ms | 300ms |
Thresholds come from ratingForMetric in features/analytics/lib/analytics-db.ts. The client reports each metric's rating from next/web-vitals and buffers them into one POST per debounce window to /api/analytics/web-vitals.
Treat performance as release criteria for major clone launches: run Lighthouse on /, /opportunities, and /store after deploy — compare with Admin analytics the following week.
useActionStatefeatures/reviews/components/review-form.tsx |
useOptimistic | hooks/use-realtime.ts, hooks/use-realtime-opportunities.ts |
Server Actions + revalidatePath | app/_actions/*.ts |
Prefer Server Components for list/detail shells; isolate 'use client' to forms, tunnel, wallet, and viz widgets.
Docs and marketing widgets load via dynamic(..., { ssr: false }) in mdx-heavy-components.tsx. Top-level Mermaid/Shiki on the server caused 30s loads and 503s in production — see Docker deployment.
<Code> is async server Shikicomponents/docs/code.tsx calls highlightCodeToHtml once per block — do not add client-side highlighters on the same page.
staticPageGenerationTimeout: 180 in next.config.mjs — large doc trees or many locales need incremental static generation discipline; trim scanDocsStaticParams scope if builds exceed CI limits.
next.config.mjs sets output: 'standalone' with outputFileTracingRoot, serverExternalPackages (Firebase, Auth.js, Solana, nodemailer), and outputFileTracingIncludes (i18n, locales, docs, ring-config, server.ts) so container images trace only the server bundles they need.
next.config.mjs enables WebP/AVIF (images.formats) and remote patterns for Google avatars, Google Fonts, Vercel Blob, and cdn.ring-platform.org — plus per-clone patterns via collectCloneImageRemotePatterns. Add new CDN hostnames to images.remotePatterns when onboarding a clone.
WebVitalsProvider (components/providers/web-vitals-provider.tsx), rendered in app-client-shell.tsx017_ring_analytics_schema.sqlGET /api/analytics/web-vitals?scope=platform (admin)ANALYTICS_DISABLE_STORAGE=true for load testsFull monitoring reference: Monitoring & analytics.
Implementation patterns (Firebase cache(), static generation, edge notes) live in Development: Performance and Features: Performance patterns — verify examples against postgres-primary clones before copying Firebase-specific snippets.