@suprsonic/react

React components for integrating SuprSonic blog content into your applications with metadata generation.

Installation

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

🚀 Revolutionary Metadata System

NEW in v0.2.0: Eliminate complex page logic with our groundbreaking clean metadata API. Generate enterprise-grade SEO metadata with just 2-3 lines of code.

Quick Start with Metadata

import { 
  SuprSonicBlogMetadata,
  SuprSonicTopicMetadata, 
  SuprSonicArticleMetadata 
} from '@suprsonic/react';

// Site-wide metadata (layout.tsx) - 2 lines of code
export async function generateMetadata(): Promise<Metadata> {
  return SuprSonicBlogMetadata({
    apiKey: process.env.SUPRSONIC_API_KEY!,
    baseUrl: process.env.NEXT_PUBLIC_SUPRSONIC_BASE_URL!,
  });
}

// Topic-specific metadata - 3 lines of code  
export async function generateMetadata({ params }: TopicPageProps): Promise<Metadata> {
  const { topic } = await params;
  return SuprSonicTopicMetadata({
    apiKey: process.env.SUPRSONIC_API_KEY!,
    baseUrl: process.env.NEXT_PUBLIC_SUPRSONIC_BASE_URL!,
    topic: decodeURIComponent(topic)
  });
}

// Article-specific metadata - 3 lines of code
export async function generateMetadata({ params }: ArticlePageProps): Promise<Metadata> {
  const { slug } = await params;
  return SuprSonicArticleMetadata({
    apiKey: process.env.SUPRSONIC_API_KEY!,
    baseUrl: process.env.NEXT_PUBLIC_SUPRSONIC_BASE_URL!,
    slug: decodeURIComponent(slug)
  });
}

What You Get Automatically

• ✅ Complete Open Graph - Perfect social media previews
• ✅ Twitter Cards - Rich Twitter sharing with images
• ✅ Schema.org Structured Data - Enhanced search engine understanding
• ✅ Account-Specific Branding - Your client's logo, colors, and business info
• ✅ Error Resilience - Graceful fallbacks when API calls fail
• ✅ Zero Configuration - All settings API integration handled internally

Blog Components

1. Get Your API Key

First, you'll need to generate an API key from your SuprSonic dashboard:

1. Log into your SuprSonic account
2. Go to Settings → Organization → API Keys
3. Generate a new API key
4. Copy the key (it starts with sk_)

2. Basic Blog Integration

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

function MyBlog() {
  return (
    <SuprSonicBlog 
      apiKey="sk_your_api_key_here"
      baseUrl="https://api.suprsonic.com/v1"
      showSearch={true}
      showTags={true}
      articlesPerPage={10}
    />
  );
}

3. Single Article View

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

function ArticlePage({ slug }: { slug: string }) {
  return (
    <SuprSonicArticle 
      apiKey="sk_your_api_key_here"
      baseUrl="https://api.suprsonic.com/v1"
      slug={slug}
      showRelatedArticles={true}
    />
  );
}

4. Topic Pages

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

function TopicPage({ topic }: { topic: string }) {
  return (
    <SuprSonicTopicPage
      apiKey="sk_your_api_key_here"
      baseUrl="https://api.suprsonic.com/v1"
      topic={topic}
      showSearch={true}
      showRelatedTopics={true}
    />
  );
}

Components

Metadata Functions

Blog Components

SEO Components

Advanced Features

Environment Configuration

For local development, you can override the API URL:

<SuprSonicBlog 
  apiKey="sk_your_api_key_here"
  baseUrl="http://localhost:3000/api/v1"  // For local development
/>

Custom Styling

You can override styles by targeting the CSS classes:

.suprsonic-blog {
  /* Blog container */
}

.suprsonic-article-card {
  /* Individual article cards */
}

.suprsonic-search {
  /* Search component */
}

.suprsonic-tags {
  /* Tag filter component */
}

.suprsonic-pagination {
  /* Pagination component */
}

.suprsonic-article-content {
  /* Article content area */
}

.suprsonic-article-hero {
  /* Article hero image */
}

.suprsonic-topic-header {
  /* Topic page headers */
}

SEO Route Integration

// app/sitemap.xml/route.ts
import { SuprSonicSitemap } from '@suprsonic/react';

export async function GET() {
  return SuprSonicSitemap({
    apiKey: process.env.SUPRSONIC_API_KEY!,
    baseUrl: process.env.NEXT_PUBLIC_SUPRSONIC_BASE_URL!,
  });
}

// app/rss.xml/route.ts
import { SuprSonicRSS } from '@suprsonic/react';

export async function GET() {
  return SuprSonicRSS({
    apiKey: process.env.SUPRSONIC_API_KEY!,
    baseUrl: process.env.NEXT_PUBLIC_SUPRSONIC_BASE_URL!,
  });
}

TypeScript Support

This package includes comprehensive TypeScript definitions. All props are fully typed:

import type { 
  SuprSonicBlogProps, 
  SuprSonicArticleProps,
  SuprSonicTopicPageProps,
  Article,
  BlogMetadata,
  SEOResponse
} from '@suprsonic/react';

Business Impact

For Developers

• Eliminates Complexity: 3-line functions replace 50+ lines of metadata logic
• Error Resilience: All API calls, error handling, and fallbacks managed internally
• Professional Results: Enterprise-grade SEO without the learning curve
• Zero Configuration: No need to understand SuprSonic's API structure

For Businesses

• Account-Specific Branding: Your logo, colors, and business info automatically applied
• Professional SEO: Complete Open Graph, Twitter Cards, and structured data
• Instant Integration: Add a professional blog to any website in minutes
• White-Label Experience: Fully branded content that matches your business

Examples

Check out the complete examples in the /examples directory:

• Next.js Basic: Complete integration example with Next.js App Router at packages/integrations/react/examples/nextjs-basic
• Metadata Implementation: Demonstrates clean metadata functions throughout
• SEO Integration: Shows proper SEO route implementation

Production Deployment

For production deployments:

1. Store your API key as an environment variable
2. Use the default production API URL (no baseUrl needed)
3. Implement proper error boundaries for robustness

// Production setup
<SuprSonicBlog 
  apiKey={process.env.NEXT_PUBLIC_SUPRSONIC_API_KEY}
/>

API Authentication

The components use your API key to authenticate requests. The API key:

• Identifies your account automatically
• Provides access only to your published content
• Can be generated and revoked from your dashboard
• Should be kept secure (use environment variables in production)

What's New in v0.2.0

🚀 Revolutionary Metadata System

• SuprSonicBlogMetadata(): Site-wide metadata generation
• SuprSonicTopicMetadata(): Topic-specific SEO optimization
• SuprSonicArticleMetadata(): Article-specific metadata with structured data
• Internal API Management: All settings API calls handled automatically
• Error Resilience: Graceful fallbacks for any API failures

🎯 Enhanced Components

• SuprSonicTopicPage: New component for topic-based content discovery
• SEO Component Library: Complete set of SEO integration components
• Improved TypeScript: Enhanced type definitions and IntelliSense support

🔧 Developer Experience

• Zero Configuration: Metadata functions handle all complexity internally
• Clean API: Simple function calls replace complex page logic
• Professional Results: Enterprise-grade SEO without manual configuration

Upgrade from v0.1.x

If you're upgrading from v0.1.x:

1. Update the package: npm install @suprsonic/react@0.2.0
2. Replace complex metadata logic with simple function calls
3. Enjoy the new clean API and enhanced functionality

Support

• Documentation
• API Reference
• Examples
• Support