@suprsonic/react NPM

@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
}