@suprsonic/react

A comprehensive React component library for integrating SuprSonic blog functionality into your Next.js applications. Features beautiful design, built-in loading states, search, filtering, pagination, and seamless theming integration.

Installation

npm install @suprsonic/react
# or
yarn add @suprsonic/react
# or
pnpm add @suprsonic/react

Quick Start

1. Import Styles

Import the CSS styles in your app's root component or layout:

import '@suprsonic/react/styles';

2. Add Blog Component

import { SuprSonicBlog } from '@suprsonic/react';

function BlogPage() {
  return (
    <SuprSonicBlog
      apiKey="your-api-key"
      baseUrl="https://your-domain.com" // Optional - defaults to production
    />
  );
}

Components

SuprSonicBlog

The main blog component with full feature parity to blog-internal:

import { SuprSonicBlog } from '@suprsonic/react';

<SuprSonicBlog
  apiKey="your-api-key"
  baseUrl="https://your-domain.com"
  pageSize={12}
  showSearch={true}
  showTags={true}
  theme="system" // Auto-detect or inherit from parent
  settingsCacheTTL={4 * 60 * 60 * 1000} // 4 hours
  bustSettingsCache={false} // Force fresh settings
  onArticleClick={(article) => console.log('Article clicked:', article)}
  onTagClick={(tag) => console.log('Tag clicked:', tag)}
  onError={(error) => console.error('Blog error:', error)}
  className="my-blog"
/>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiKey | string | Required | Your SuprSonic API key | | baseUrl | string | 'https://api.suprsonic.com' | Base URL for API calls | | className | string | undefined | Additional CSS classes | | pageSize | number | 12 | Number of articles per page | | showSearch | boolean | true | Show search functionality | | showTags | boolean | true | Show tag filtering | | theme | 'light' \| 'dark' \| 'system' | undefined | Theme override (inherits from parent if undefined) | | settingsCacheTTL | number | 14400000 | Settings cache TTL in milliseconds (4 hours) | | bustSettingsCache | boolean | false | Force fresh settings fetch on mount | | onArticleClick | function | undefined | Custom article click handler | | onTagClick | function | undefined | Custom tag click handler | | onError | function | undefined | Error handler |

SuprSonicArticle

Display individual articles with rich content and related articles:

import { SuprSonicArticle } from '@suprsonic/react';

<SuprSonicArticle
  apiKey="your-api-key"
  baseUrl="https://your-domain.com"
  slug="your-article-slug"
  showRelated={true}
  onTagClick={(tag) => console.log('Tag clicked:', tag)}
/>

SuprSonicTopicPage

Display articles filtered by topic/tag:

import { SuprSonicTopicPage } from '@suprsonic/react';

<SuprSonicTopicPage
  apiKey="your-api-key"
  baseUrl="https://your-domain.com"
  topic="react"
  showBackButton={true}
  onBackClick={() => window.history.back()}
/>

Individual Components

Build custom layouts using individual components:

ArticleCard

import { ArticleCard } from '@suprsonic/react';

<ArticleCard
  article={article}
  baseUrl="https://your-domain.com"
  onArticleClick={(article) => console.log(article)}
  onTagClick={(tag) => console.log(tag)}
/>

SearchForm

import { SearchForm } from '@suprsonic/react';

<SearchForm
  initialQuery=""
  onSearch={(query) => console.log('Search:', query)}
  onClear={() => console.log('Clear search')}
  placeholder="Search articles..."
/>

Pagination

import { Pagination } from '@suprsonic/react';

<Pagination
  currentPage={1}
  totalPages={10}
  hasNext={true}
  hasPrev={false}
  onPageChange={(page) => console.log('Page:', page)}
/>

Loading States

import { ArticlesListSkeleton } from '@suprsonic/react';

<ArticlesListSkeleton
  count={12}
  showHeader={true}
  showPagination={true}
/>

Theming & Customization

CSS Custom Properties

The package uses CSS custom properties that automatically inherit from your existing design system:

:root {
  /* Colors - automatically inherited from your Tailwind/CSS setup */
  --primary: 221.2 83.2% 53.3%;
  --secondary: 210 40% 96%;
  --muted: 210 40% 96%;
  --card: 0 0% 100%;
  --border: 214.3 31.8% 91.4%;
  
  /* Blog-specific variables you can override */
  --blog-primary-color: hsl(221.2 83.2% 53.3%);
  --blog-font-family: system-ui, sans-serif;
  --blog-container-max-width: 72rem;
  --blog-border-radius: 0.5rem;
}

Tailwind CSS Integration

If you have Tailwind CSS configured, the components will automatically inherit:

• Your custom colors
• Your font families
• Your spacing scales
• Your border radius settings
• Your breakpoints

Custom CSS Classes

Override styling with CSS classes:

/* Override blog container */
.my-blog .blog-container {
  max-width: 1200px;
  padding: 2rem;
}

/* Customize article cards */
.my-blog .article-card {
  border-radius: 12px;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}

/* Custom tag styling */
.my-blog .tag {
  background: linear-gradient(45deg, #667eea 0%, #764ba2 100%);
  color: white;
}

Automatic Theme Detection

The components intelligently detect and inherit your app's theme:

// Inherit from parent app (default behavior)
<SuprSonicBlog apiKey="your-key" />

// Force system preference detection
<SuprSonicBlog apiKey="your-key" theme="system" />

// Override with specific theme
<SuprSonicBlog apiKey="your-key" theme="dark" />

Theme Detection Methods:

1. Manual override (theme prop)
2. HTML class="dark" or data-theme="dark"
3. Body class="dark"
4. CSS custom property --theme: dark
5. System preference (prefers-color-scheme)

Dark Mode Integration

Works automatically with popular theme systems:

/* Next.js with next-themes */
.dark {
  --blog-primary-color: hsl(217.2 91.2% 59.8%);
  --blog-muted-color: hsl(217.2 32.6% 17.5%);
}

/* Tailwind CSS dark mode */
@media (prefers-color-scheme: dark) {
  :root {
    --blog-primary-color: hsl(217.2 91.2% 59.8%);
  }
}

Intelligent Settings Caching

The package automatically caches branding settings from your SuprSonic API:

<SuprSonicBlog
  apiKey="your-key"
  settingsCacheTTL={4 * 60 * 60 * 1000} // 4 hours (default)
  bustSettingsCache={false} // Force fresh fetch
/>

What gets cached and applied:

• primary_color → --blog-primary-color
• font_display → --blog-font-display
• font_body → --blog-font-body
• style_density → data-blog-density attribute
• corner_radius → data-blog-radius attribute

Cache features:

• 4-hour default TTL (configurable)
• Shared across components with same API key
• Cache busting prop for development
• Immediate CSS application when settings change

// Development: Always fetch fresh settings
<SuprSonicBlog apiKey="your-key" bustSettingsCache={true} />

// Production: Long cache for performance
<SuprSonicBlog apiKey="your-key" settingsCacheTTL={24 * 60 * 60 * 1000} />

Advanced Usage

Custom Error Handling

import { SuprSonicBlog, Toaster } from '@suprsonic/react';
import { toast } from 'sonner';

<SuprSonicBlog
  apiKey="your-api-key"
  onError={(error) => {
    console.error('Blog error:', error);
    toast.error('Failed to load blog content');
  }}
/>
<Toaster />

Custom Navigation

import { SuprSonicBlog } from '@suprsonic/react';
import { useRouter } from 'next/navigation';

function BlogWithCustomNavigation() {
  const router = useRouter();
  
  return (
    <SuprSonicBlog
      apiKey="your-api-key"
      onArticleClick={(article) => {
        router.push(`/blog/${article.slug}`);
      }}
      onTagClick={(tag) => {
        router.push(`/blog/topic/${encodeURIComponent(tag)}`);
      }}
    />
  );
}

Server-Side Metadata

For SEO and metadata, use the server-side functions:

// In your page component
import { SuprSonicBlogMetadata } from '@suprsonic/react/server';

export async function generateMetadata() {
  return SuprSonicBlogMetadata({
    apiKey: process.env.SUPRSONIC_API_KEY!,
    baseUrl: process.env.NEXT_PUBLIC_SUPRSONIC_API_BASE_URL,
  });
}

TypeScript Support

Full TypeScript support with comprehensive type exports:

import type { 
  ArticleCardData, 
  BlogSettings, 
  PaginationInfo,
  Tag 
} from '@suprsonic/react';

// Use types in your custom components
function CustomBlogComponent() {
  const [articles, setArticles] = useState<ArticleCardData[]>([]);
  const [settings, setSettings] = useState<BlogSettings | null>(null);
  
  // Your custom implementation
}

Performance Features

• Lazy Loading: All images are lazy-loaded by default
• Debounced Search: Search queries are debounced for optimal performance
• Skeleton Loading: Beautiful loading states while content loads
• Optimized Rendering: React best practices for efficient re-renders

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

Proprietary License. All rights reserved. See LICENSE for details.

For more information, visit SuprSonic Documentation or contact [email protected].