@fireship-ai/blog

A beautiful, SEO-friendly blog package for Next.js 13+ with Fireship.ai API integration. Features modern UI design, interactive components, and seamless integration.

Features

• 🎨 Modern UI: Clean design with NextUI and TailwindCSS
• 📝 Blog Components: Ready-to-use blog post viewer and navigation
• 🎯 SEO Optimized: Automatic meta tags and Open Graph support
• 🌙 Dark Mode: Full dark/light mode support with zinc color palette
• 📱 Responsive: Mobile-first design that works on all devices
• ⚡ Server Components: Next.js 13+ App Router with SSR support
• 🔗 Interactive: Like, save, and share functionality built-in
• 🎨 Customizable: Sidebar layouts and content organization

Installation

npm install fireship-ai-blog
# or
yarn add fireship-ai-blog
# or
bun add fireship-ai-blog

Quick Start

1. Add Environment Variable

# .env.local
NEXT_PUBLIC_FIRESHIP_BLOG_PUBLISHABLE_KEY=your_api_key_here

2. Create API Route

// app/api/fireship-blog/[...path]/route.ts
import { createFireshipProxyHandler } from 'fireship-ai-blog';

const base = createFireshipProxyHandler({
  apiBase: 'https://fireship.ai/api/blog',
  getApiKey: () =>
    process.env.FIRESHIP_BLOG_API_KEY ||
    process.env.NEXT_PUBLIC_FIRESHIP_BLOG_PUBLISHABLE_KEY,
  allowOrigin: 'http://localhost:3000',
  domain: 'your-domain.com' // Your website domain
});

export async function GET(req: Request, ctx: { params: Promise<{ path?: string[] }> }) {
  const resolved = ctx?.params ? await ctx.params : undefined;
  return base.GET(req, { params: resolved });
}

export function OPTIONS() {
  return base.OPTIONS();
}

3. Use the Component

// app/blog/page.tsx
import { FireshipBlog } from 'fireship-ai-blog'

export default function BlogPage() {
  return <FireshipBlog />
}

That's it! The component handles:

• ✅ Blog post listing
• ✅ Individual post viewing (with URL slugs)
• ✅ Navigation between posts
• ✅ All API calls internally
• ✅ Loading states and error handling

Dependencies

The package automatically includes all core dependencies:

• TipTap (rich text editor)
• React Markdown (markdown rendering)
• Recharts (analytics charts)
• Utility libraries (clsx, tailwind-merge)

You only need these peer dependencies (likely already in your project):

• React 18+
• Next.js 13+
• Tailwind CSS 3+
• Lucide React (for icons)

Install peer dependencies if missing:

npm install react react-dom next tailwindcss lucide-react

Setup

1. Environment Variables

Add your Fireship.ai API key to your .env.local file:

NEXT_PUBLIC_FIRESHIP_BLOG_PUBLISHABLE_KEY=your_api_key_here

2. Import Styles

Add the CSS import to your globals.css file:

@import 'fireship-blog/styles/blog.css';

3. Tailwind Configuration

Add the package to your tailwind.config.js:

module.exports = {
  content: [
    // ... your existing content paths
    './node_modules/fireship-blog/**/*.{js,ts,jsx,tsx}',
  ],
  // ... rest of your config
}

Usage

Basic Blog Page

Create a blog page at app/blog/page.tsx:

import { FireshipBlog } from 'fireship-blog';

export default function BlogPage() {
  return <FireshipBlog />;
}

Single Post Page

Create a dynamic post page at app/blog/[slug]/page.tsx:

import { FireshipBlog } from 'fireship-blog';

interface BlogPostPageProps {
  params: { slug: string };
}

export default function BlogPostPage({ params }: BlogPostPageProps) {
  return <FireshipBlog slug={params.slug} />;
}

Admin Dashboard

Create an admin page at app/blog/admin/page.tsx:

import { FireshipBlogAdmin } from 'fireship-blog';

export default function BlogAdminPage() {
  return <FireshipBlogAdmin />;
}

Category/Tag Pages

import { FireshipBlog } from 'fireship-blog';

export default function CategoryPage({ params }: { params: { category: string } }) {
  return <FireshipBlog category={params.category} />;
}

Components

FireshipBlog

The main blog component for displaying posts and single post views.

<FireshipBlog
  domain="your-domain.com" // Required: Your website domain
  slug="optional-post-slug"
  category="optional-category"
  tag="optional-tag"
  limit={10}
  showRelatedPosts={true}
  showNavigation={true}
  customTheme={{
    primaryColor: '#3b82f6',
    glassEffect: true,
  }}
/>

FireshipBlogAdmin

Admin dashboard for managing posts, analytics, and theme settings.

<FireshipBlogAdmin
  onSave={(post) => console.log('Post saved:', post)}
  onDelete={(postId) => console.log('Post deleted:', postId)}
/>

PostEditor

Rich text editor component with markdown support.

<PostEditor
  post={existingPost}
  onSave={async (postData) => {
    // Handle save
  }}
  onCancel={() => {
    // Handle cancel
  }}
/>

PostCard

Individual post card component.

<PostCard
  post={blogPost}
  onClick={(post) => router.push(`/blog/${post.slug}`)}
  showAnalytics={true}
/>

AnalyticsDashboard

Analytics dashboard with charts and metrics.

<AnalyticsDashboard
  postId="optional-specific-post"
  dateRange={{
    from: '2024-01-01',
    to: '2024-12-31'
  }}
/>

ThemeSettings

Theme customization component.

<ThemeSettings
  settings={currentTheme}
  onSave={async (newTheme) => {
    // Save theme settings
  }}
/>

Hooks

useFireshipPosts

Hook for fetching and managing blog posts.

import { useFireshipPosts } from 'fireship-blog';

function BlogComponent() {
  const {
    posts,
    loading,
    error,
    hasMore,
    loadMore,
    refresh,
    totalCount
  } = useFireshipPosts({
    category: 'tech',
    limit: 10,
    status: 'published'
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <div>
      {posts.map(post => (
        <PostCard key={post.id} post={post} />
      ))}
      {hasMore && (
        <button onClick={loadMore}>Load More</button>
      )}
    </div>
  );
}

useFireshipPost

Hook for fetching a single post.

import { useFireshipPost } from 'fireship-blog';

function SinglePostComponent({ slug }: { slug: string }) {
  const { post, loading, error } = useFireshipPost(slug);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!post) return <div>Post not found</div>;

  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  );
}

useFireshipTheme

Hook for managing theme settings.

import { useFireshipTheme } from 'fireship-blog';

function ThemeToggle() {
  const { theme, updateTheme } = useFireshipTheme();

  const toggleGlassEffect = () => {
    updateTheme({
      ...theme,
      glassEffect: !theme.glassEffect
    });
  };

  return (
    <button onClick={toggleGlassEffect}>
      {theme.glassEffect ? 'Disable' : 'Enable'} Glass Effect
    </button>
  );
}

API Reference

Core API Functions

import {
  getPosts,
  getPostBySlug,
  getRelatedPosts,
  submitPost,
  getAnalytics,
  updateThemeSettings
} from 'fireship-blog';

// Fetch posts
const posts = await getPosts({
  page: 1,
  limit: 10,
  category: 'tech',
  status: 'published'
});

// Get single post
const post = await getPostBySlug('my-blog-post');

// Submit new/updated post
const savedPost = await submitPost({
  title: 'My New Post',
  content: '# Hello World\n\nThis is my post content.',
  status: 'published'
});

// Get analytics
const analytics = await getAnalytics({
  postId: 'optional-post-id',
  dateFrom: '2024-01-01',
  dateTo: '2024-12-31'
});

Markdown Utilities

import {
  markdownToHtml,
  htmlToMarkdown,
  calculateReadingTime,
  extractExcerpt,
  validateMarkdown
} from 'fireship-blog';

// Convert markdown to HTML
const html = await markdownToHtml('# Hello World');

// Calculate reading time
const readingTime = calculateReadingTime(markdownContent);

// Extract excerpt
const excerpt = extractExcerpt(markdownContent, 160);

// Validate markdown
const { isValid, errors, warnings } = validateMarkdown(content);

Theme Customization

Default Theme

import { defaultTheme } from 'fireship-blog';

const customTheme = {
  ...defaultTheme,
  primaryColor: '#ef4444', // Red
  secondaryColor: '#64748b', // Slate
  fontFamily: 'sf-pro',
  fontSize: 'lg',
  glassEffect: true,
  borderRadius: 'xl'
};

Tailwind Config Presets

Add these presets to your tailwind.config.js:

module.exports = {
  theme: {
    extend: {
      fontFamily: {
        'inter': ['Inter', 'sans-serif'],
        'sf-pro': ['-apple-system', 'BlinkMacSystemFont', 'SF Pro Display', 'sans-serif'],
      },
      colors: {
        'fireship-primary': 'var(--fireship-primary)',
        'fireship-secondary': 'var(--fireship-secondary)',
      },
      backdropBlur: {
        'fireship': '20px',
      }
    }
  }
}

SEO Features

The package automatically generates:

• Meta Tags: Title, description, keywords
• Open Graph: og:title, og:description, og:image, og:type
• Twitter Cards: twitter:card, twitter:title, twitter:description, twitter:image
• Structured Data: JSON-LD for articles
• Canonical URLs: Prevents duplicate content issues

Analytics Integration

Track various metrics:

• Page Views: Automatic view tracking
• Engagement: Likes, comments, shares
• Referrers: Traffic sources
• Backlinks: Incoming link discovery
• Performance: Reading time, bounce rate

Backlink Trading Network

Participate in Fireship.ai's backlink trading network:

1. Automatic Discovery: Find relevant blogs in your niche
2. Quality Scoring: AI-powered relevance and authority scoring
3. Trading Proposals: Automated backlink exchange proposals
4. Performance Tracking: Monitor backlink impact on SEO

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type {
  BlogPost,
  ThemeSettings,
  BlogAnalytics,
  FireshipBlogProps
} from 'fireship-blog';

const post: BlogPost = {
  id: '1',
  slug: 'my-post',
  title: 'My Blog Post',
  content: '# Hello World',
  // ... other required fields
};

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see the LICENSE file for details.

Support

• 📧 Email: [email protected]
• 💬 Discord: Fireship Community
• 📖 Documentation: docs.fireship.ai
• 🐛 Issues: GitHub Issues

Changelog

v1.0.0

• Initial release
• Core blog functionality
• Admin dashboard
• Analytics integration
• Theme customization
• SEO optimization
• Backlink trading network