nextjs-smart-blog

A plug-and-play blog component library for Next.js with auto dark mode, search, categories, pagination, and beautiful UI. One CLI command sets everything up automatically.

Features

• 🎨 Auto dark mode — detects prefers-color-scheme from the browser
• 🔍 Search — filter posts by title and description
• 🏷️ Category tabs — dynamic filtering by post category
• 📄 Pagination — always visible, clean UI
• 🎭 4 built-in themes — default, dark, minimal, ocean
• 📦 Zero config — CLI generates all routes automatically
• 🚀 TypeScript — full type safety out of the box
• 💅 Beautiful cards — gradient covers, badges, author rows
• 📖 Rich detail pages — hero covers, code blocks, related posts

Installation

npm install nextjs-smart-blog

Quick Start

Step 1 — Run the CLI inside your Next.js project

npx nextjs-smart-blog init

This automatically:

• Creates all blog routes
• Patches next.config.ts with transpilePackages
• Generates sample posts

app/
└── blog/
    ├── page.tsx          ← /blog  (card grid + search + categories)
    ├── layout.tsx        ← imports the CSS
    ├── posts.json        ← sample posts (edit freely)
    └── [slug]/
        └── page.tsx      ← /blog/[slug]  (detail view)

Step 2 — Start your dev server

npm run dev

Step 3 — Open in browser

| URL | Page | |-----|------| | http://localhost:3000/blog | Blog listing with search + categories | | http://localhost:3000/blog/getting-started-with-nextjs | Post detail | | http://localhost:3000/blog/mastering-react-hooks | Post detail |

Usage

All-in-one router (recommended)

The CLI generates this automatically:

// app/blog/page.tsx
"use client";
import { BlogRouter } from "nextjs-smart-blog";

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

BlogRouter handles listing + detail navigation internally — no extra routing needed.

Separate components with Next.js router

// app/blog/page.tsx
"use client";
import { BlogPage } from "nextjs-smart-blog";
import { useRouter } from "next/navigation";

export default function BlogRoute() {
  const router = useRouter();
  return (
    <BlogPage
      onSelectPost={(post) => router.push(`/blog/${post.slug}`)}
    />
  );
}

// app/blog/[slug]/page.tsx
import { BlogDetailPage } from "nextjs-smart-blog";

export default async function PostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  return <BlogDetailPage slug={slug} />;
}

Use your own data

import { BlogRouter } from "nextjs-smart-blog";
import posts from "./my-posts.json";

export default function BlogPage() {
  return <BlogRouter posts={posts} />;
}

Import styles manually

import "nextjs-smart-blog/styles";

API

<BlogRouter>

All-in-one component — handles listing, detail view, and navigation internally.

| Prop | Type | Default | Description | |------|------|---------|-------------| | theme | BlogTheme | Auto-detected | Force a theme | | posts | BlogPost[] | Built-in JSON | Override with your own data |

<BlogPage>

Card grid with search, category tabs, and pagination.

| Prop | Type | Default | Description | |------|------|---------|-------------| | posts | BlogPost[] | Built-in JSON | Override with your own data | | onSelectPost | (post: BlogPost) => void | undefined | Called when a card is clicked | | theme | BlogTheme | Auto-detected | Force a theme |

<BlogDetailPage>

Full post view with hero cover, content, and related posts.

| Prop | Type | Default | Description | |------|------|---------|-------------| | slug | string | required | Post slug to display | | post | BlogPost | Auto-fetched | Override with your own data | | theme | BlogTheme | Auto-detected | Force a theme | | onBack | () => void | undefined | Called when back button is clicked | | onSelectPost | (post: BlogPost) => void | undefined | Called when a related post is clicked |

<BlogCard>

Single card component.

| Prop | Type | Default | Description | |------|------|---------|-------------| | post | BlogPost | required | Post data | | theme | BlogTheme | "default" | Visual theme | | onClick | (post: BlogPost) => void | undefined | Called when clicked |

Helper functions

import { getAllPosts, getPostBySlug, getAllSlugs } from "nextjs-smart-blog";

const posts  = getAllPosts();             // BlogPost[]
const post   = getPostBySlug("my-slug"); // BlogPost | undefined
const slugs  = getAllSlugs();            // string[]

Types

import type { BlogPost, BlogTheme } from "nextjs-smart-blog";

type BlogPost = {
  slug: string;
  title: string;
  date: string;
  description: string;
  content: string;
  category?: string;
};

type BlogTheme = "default" | "dark" | "minimal" | "ocean";

Post format

Edit app/blog/posts.json after running init:

[
  {
    "slug": "my-first-post",
    "title": "My First Post",
    "date": "2026-05-14",
    "category": "Technology",
    "description": "A short description shown on the card.",
    "content": "# My First Post\n\nParagraph text here.\n\n## Subheading\n\n- List item\n- Another item\n\n```js\nconst x = 42;\n```"
  }
]

Supported markdown in content

| Syntax | Output | |--------|--------| | # Heading | <h1> | | ## Heading | <h2> | | ### Heading | <h3> | | **bold** | <strong> | | - item | bullet list | | 1. item | numbered list | | ```lang | syntax-highlighted code block |

Themes

| Theme | Description | |-------|-------------| | default | Light, clean, blue-grey background | | dark | Dark grey, high contrast | | minimal | White background, subtle shadows | | ocean | Deep navy blue |

Theme is auto-detected from the browser's prefers-color-scheme. Override with:

<BlogRouter theme="ocean" />

CLI

npx nextjs-smart-blog init

Generates blog routes inside your Next.js project. Safe to re-run — skips files that already exist.

What it creates:

app/blog/page.tsx          ← blog listing page
app/blog/layout.tsx        ← CSS import
app/blog/posts.json        ← sample posts
app/blog/[slug]/page.tsx   ← post detail page

What it patches:

• next.config.ts — adds transpilePackages: ["nextjs-smart-blog"]

Development

Install dependencies

npm install

Build

npm run build

Outputs to dist/:

• dist/index.js — CJS bundle
• dist/index.mjs — ESM bundle
• dist/blog.css — styles
• dist/*.d.ts — TypeScript declarations

Watch mode

npm run dev

Pack for local testing

npm pack
# creates nextjs-smart-blog-0.1.1.tgz

Install locally in a Next.js project

cd /path/to/your-nextjs-app
npm install /path/to/nextjs-smart-blog/nextjs-smart-blog-0.1.1.tgz
npx nextjs-smart-blog init
npm run dev

Project Structure

nextjs-smart-blog/
├── bin/
│   └── init.js                ← CLI script
├── src/
│   ├── components/
│   │   └── BlogCard.tsx       ← Card component
│   ├── data/
│   │   └── posts.json         ← Built-in sample posts
│   ├── lib/
│   │   ├── posts.ts           ← Data helpers
│   │   └── withBlogRoutes.tsx ← BlogRouter component
│   ├── pages/
│   │   ├── BlogPage.tsx       ← Listing page
│   │   └── BlogDetailPage.tsx ← Detail page
│   ├── styles/
│   │   └── blog.css           ← All styles + themes
│   ├── types/
│   │   └── blog.ts            ← TypeScript types
│   └── index.ts               ← Main export
├── dist/                      ← Build output (gitignored)
├── .gitignore
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── README.md

License

MIT

Contributing

PRs welcome. Please open an issue first to discuss what you'd like to change.

Roadmap

• [ ] MDX support
• [ ] RSS feed generation
• [ ] SEO meta tags helper
• [ ] Reading time estimate
• [ ] Table of contents
• [ ] Social share buttons
• [ ] Comments integration
• [ ] Image support in posts