Embed & Widget System
Relevant source files
The following files were used as context for generating this wiki page:
The Embed & Widget System is the core delivery mechanism for displaying social proof within the KudosWall ecosystem. It allows users to integrate collected testimonials—both text and video—into third-party websites (such as Webflow, Framer, and Carrd) using high-performance, edge-optimized widgets. The system focuses on zero layout shift (CLS), rapid loading times, and deep UI customization.
Sources: README.md:12-25, apps/web/src/lib/comparisons.tsx:55-75
Architecture and Data Flow
The system operates as a distributed architecture where testimonial data is fetched from a Neon Postgres database and served via an edge-compatible Next.js proxy. This ensures sub-100ms loading times globally. The widgets are rendered as iframes or native components that inherit styles from the parent project or use bespoke design tokens.
Request Flow for Embedded Widgets
The following diagram illustrates the sequence of events when a visitor views a page containing a KudosWall embed.
Widget Configurations and Personalization
Widgets are highly configurable through settingsJson. For "Pro" tier users, these settings can be dynamically overridden via URL search parameters to match specific page aesthetics without modifying the base widget definition.
Configuration Parameters
| Parameter | Type | Description |
|---|---|---|
layout | string | Selection of layout type: Masonry, Carousel, Marquee, or List. |
theme | string | Visual mode, typically "light" or "dark". |
accentColor | hex | Primary color for buttons, stars, and accents. |
maxItems | number | Limit for the number of testimonials fetched (default 20, max 100). |
filterMinRating | number | Minimum star rating required for a testimonial to appear. |
fontFamily | string | Supports 35+ Google Fonts or a "custom" font URL. |
hideBadge | boolean | Toggle to remove "Powered by KudosWall" branding (Pro only). |
Sources: apps/web/src/app/embed/[id]/page.tsx:43-65, apps/web/src/app/wall/[slug]/page.tsx:75-95, apps/web/src/lib/comparisons.tsx:430-450
Performance Optimization
The system employs several technical strategies to maintain high performance and SEO visibility:
- Edge Caching: The embed routes use
revalidate = 300to cache content at the edge for 5 minutes. Sources: apps/web/src/app/embed/[id]/page.tsx:12 - Zero Layout Shift: Widgets use advanced CSS-first rendering and fixed placeholders to prevent the page from "jumping" during load. Sources: apps/web/src/lib/comparisons.tsx:105-110
- Lazy Loading: Video components and heavy assets are lazy-loaded, ensuring they only impact performance when scrolled into the viewport. Sources: apps/web/src/lib/comparisons.tsx:900-910
- Font Preconnecting: The system generates
<link rel="preconnect">tags for Google Fonts server-side to resolve DNS in parallel with HTML parsing. Sources: apps/web/src/app/embed/[id]/page.tsx:150-160
Integration Patterns
KudosWall provides specific implementation patterns for various platforms. While most utilize a standard JavaScript snippet, the internal logic adapts to the container constraints of each platform.
Supported Platform Implementations
| Platform | Integration Method | Key Benefit |
|---|---|---|
| Carrd | Embed Element (Hidden JS) | Lightweight for one-page sites. |
| Webflow | HTML Embed Element | Matches Webflow design tokens and custom fonts. |
| Framer | Embed Component (HTML Type) | Fluid, responsive containers. |
| Notion | /embed Command | Notion-optimized URLs for clean blocks. |
| Beehiiv | Custom HTML Block | Automated subscriber social proof. |
Sources: apps/web/src/lib/platform-pages.ts:10-140, apps/web/src/lib/integration-data.ts:5-60
SEO and Structured Data
Every widget and "Wall of Love" page automatically injects JSON-LD structured data. This allows search engines to parse testimonials as Review and AggregateRating objects, potentially enabling rich snippets in search results.
// Example of Structured Data generated in EmbedPage
const jsonLd = {
"@context": "https://schema.org",
"@type": "Organization",
name: workspace.name,
aggregateRating: {
"@type": "AggregateRating",
ratingValue: calculatedAverage,
reviewCount: testimonials.length,
},
review: testimonials.map(t => ({
"@type": "Review",
author: { "@type": "Person", name: t.authorName },
reviewBody: t.content
}))
};
Sources: apps/web/src/app/embed/[id]/page.tsx:125-145, apps/web/src/app/wall/[slug]/page.tsx:145-180
Conclusion
The KudosWall Embed & Widget System is a high-fidelity delivery pipeline designed for the modern web. By combining edge-optimized server-side rendering with flexible client-side styling, it allows users to deploy social proof that is both visually integrated and performance-conscious. Its ability to serve structured SEO data and handle native video recording across diverse platforms like Webflow and Framer positions it as a robust solution for founders and agencies.