brianchitester.com Posts Polymath Profiles

Building a Modern Blog with Next.js, TypeScript, and Nextra 4

Overview

This tutorial will guide you through creating a feature-rich blog similar to this one, including:

✅ Nextra 4 with blog theme
✅ Next.js 15 with TypeScript
✅ MDX support for rich content
✅ TailwindCSS 4 for styling
✅ Tag system with filtering
✅ RSS feed generation
✅ Search functionality with Pagefind
✅ Dark/light theme switching
✅ Reading time calculation
✅ SEO optimization

Feel free to copy the content of this post and paste it into Cursor if you want to get started quickly, claude-4-sonnet can easily generate the code for you.

Step 1: Project Setup

Initialize the Project


npx create-next-app@latest my-blog --typescript --tailwind --app
cd my-blog

Install Dependencies


npm install nextra@^4.2.17 nextra-theme-blog@^4.2.17
npm install -D pagefind@^1.3.0

Update package.json


{
  "name": "my-blog",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "postbuild": "pagefind --site .next/server/app --output-path public/_pagefind",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "next": "^15.3.5",
    "nextra": "^4.2.17",
    "nextra-theme-blog": "^4.2.17",
    "react": "^19.1.0",
    "react-dom": "^19.1.0"
  },
  "devDependencies": {
    "@eslint/eslintrc": "^3",
    "@tailwindcss/postcss": "^4",
    "@types/node": "^20",
    "@types/react": "^19",
    "@types/react-dom": "^19",
    "eslint": "^9",
    "eslint-config-next": "15.3.5",
    "tailwindcss": "^4",
    "typescript": "^5",
    "pagefind": "^1.3.0"
  }
}

Step 2: Configure Next.js and Nextra

Create next.config.ts


import nextra from "nextra";
 
const withNextra = nextra({
  defaultShowCopyCode: true,
  readingTime: true,
});
 
export default withNextra({
  reactStrictMode: true,
  cleanDistDir: true,
});

Update tsconfig.json


{
  "compilerOptions": {
    "target": "ES2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Step 3: Set Up the File Structure

Create the following directory structure:


src/
├── app/
│   ├── components/
│   │   └── ActiveNavLink.jsx
│   ├── posts/
│   │   ├── get-posts.js
│   │   ├── page.jsx
│   │   └── [your-first-post]/
│   │       └── page.mdx
│   ├── rss.xml/
│   │   └── route.js
│   ├── tags/
│   │   └── [tag]/
│   │       └── page.jsx
│   ├── _meta.global.js
│   ├── globals.css
│   ├── layout.jsx
│   └── page.jsx
└── mdx-components.tsx

Step 4: Create Core Components

Create src/app/layout.jsx


import { Footer, Layout, Navbar, ThemeSwitch } from "nextra-theme-blog";
import { Head, Search } from "nextra/components";
import { getPageMap } from "nextra/page-map";
import { ActiveNavLink } from "./components/ActiveNavLink";
import "nextra-theme-blog/style.css";
import "./globals.css";
 
export const metadata = {
  title: "Your Blog Name",
  description: "Your blog description",
};
 
export default async function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <Head backgroundColor={{ dark: "#0f172a", light: "#fefce8" }} />
      <body>
        <Layout>
          <Navbar pageMap={await getPageMap()}>
            <ThemeSwitch />
          </Navbar>
 
          {children}
 
          <Footer>{new Date().getFullYear()} © Your Name.</Footer>
        </Layout>
      </body>
    </html>
  );
}

Create src/app/components/ActiveNavLink.jsx


"use client";
import Link from "next/link";
import { usePathname } from "next/navigation";
 
export function ActiveNavLink({ href, children, ...props }) {
  const pathname = usePathname();
  const isActive = pathname === href;
 
  return (
    <Link
      href={href}
      className={isActive ? "nextra-nav-link active" : "nextra-nav-link"}
      {...props}
    >
      {children}
    </Link>
  );
}

Create src/app/_meta.global.js


export default {
  index: {
    type: "page",
  },
  posts: {
    type: "page",
  },
};

Step 5: Set Up MDX Configuration

Create mdx-components.tsx


import { useMDXComponents as getBlogMDXComponents } from "nextra-theme-blog";
import type { MDXComponents } from "mdx/types";
 
const blogComponents = getBlogMDXComponents({
  h1: ({ children }) => <h1>{children}</h1>,
  DateFormatter: ({ date }) =>
    `Last updated at ${date.toLocaleDateString("en", {
      day: "numeric",
      month: "long",
      year: "numeric",
    })}`,
});
 
export function useMDXComponents(components: MDXComponents) {
  return {
    ...blogComponents,
    ...components,
  };
}

Step 6: Create Post Management System

Create src/app/posts/get-posts.js


import { normalizePages } from "nextra/normalize-pages";
import { getPageMap } from "nextra/page-map";
 
export async function getPosts() {
  const { directories } = normalizePages({
    list: await getPageMap("/posts"),
    route: "/posts",
  });
  return directories
    .filter((post) => post.name !== "index")
    .sort(
      (a, b) => new Date(b.frontMatter.date) - new Date(a.frontMatter.date)
    );
}
 
export async function getTags() {
  const posts = await getPosts();
  const tags = posts.flatMap((post) => post.frontMatter.tags || []);
  return tags;
}

Step 7: Create Pages

Create src/app/page.jsx (Homepage)


import Link from "next/link";
import { getPosts } from "./posts/get-posts";
 
export const metadata = {
  title: "Your Blog Name",
  description: "Welcome to my blog about technology and life",
};
 
export default async function HomePage() {
  const posts = await getPosts();
  const recentPosts = posts.slice(0, 3);
 
  return (
    <div>
      <div>
        <h1>Your Name</h1>
        <div>
          <p>
            Welcome to my blog! I write about technology, programming, and life.
          </p>
        </div>
        <hr />
      </div>
 
      {/* Recent Posts Section */}
      <div>
        <h2>Recent Posts</h2>
        <div>
          {recentPosts.map((post) => (
            <div key={post.route}>
              <h3>
                <Link href={post.route}>{post.frontMatter.title}</Link>
              </h3>
 
              {post.frontMatter.description && (
                <p>{post.frontMatter.description}</p>
              )}
 
              <div>
                {post.frontMatter.date && (
                  <time dateTime={post.frontMatter.date}>
                    {new Date(post.frontMatter.date).toLocaleDateString(
                      "en-US",
                      {
                        year: "numeric",
                        month: "long",
                        day: "numeric",
                      }
                    )}
                  </time>
                )}
              </div>
            </div>
          ))}
        </div>
 
        <div style={{ margin: "32px 0" }}>
          <Link href="/posts">View all posts →</Link>
        </div>
      </div>
    </div>
  );
}

Create src/app/posts/page.jsx


import Link from "next/link";
import { PostCard } from "nextra-theme-blog";
import { getPosts, getTags } from "./get-posts";
 
export const metadata = {
  title: "All Posts",
};
 
export default async function PostsPage() {
  const tags = await getTags();
  const posts = await getPosts();
  const allTags = Object.create(null);
 
  for (const tag of tags) {
    allTags[tag] ??= 0;
    allTags[tag] += 1;
  }
 
  return (
    <div data-pagefind-ignore="all">
      <h1>{metadata.title}</h1>
      <div
        className="not-prose"
        style={{ display: "flex", flexWrap: "wrap", gap: ".5rem" }}
      >
        {Object.entries(allTags).map(([tag, count]) => (
          <Link key={tag} href={`/tags/${tag}`} className="nextra-tag">
            {tag} ({count})
          </Link>
        ))}
      </div>
      {posts.map((post) => (
        <PostCard key={post.route} post={post} />
      ))}
    </div>
  );
}

Create src/app/tags/[tag]/page.jsx


import { PostCard } from "nextra-theme-blog";
import { getPosts, getTags } from "../../posts/get-posts";
 
export async function generateMetadata(props) {
  const params = await props.params;
  return {
    title: `Posts Tagged with "${decodeURIComponent(params.tag)}"`,
  };
}
 
export async function generateStaticParams() {
  const allTags = await getTags();
  return [...new Set(allTags)].map((tag) => ({ tag }));
}
 
export default async function TagPage(props) {
  const params = await props.params;
  const { title } = await generateMetadata({ params });
  const posts = await getPosts();
 
  return (
    <>
      <h1>{title}</h1>
      {posts
        .filter((post) =>
          post.frontMatter.tags?.includes(decodeURIComponent(params.tag))
        )
        .map((post) => (
          <PostCard key={post.route} post={post} />
        ))}
    </>
  );
}

Step 8: Create RSS Feed

Create src/app/rss.xml/route.js


import { getPosts } from "../posts/get-posts.js";
 
const CONFIG = {
  title: "Your Blog Name",
  siteUrl: "https://yourdomain.com",
  description: "Latest blog posts",
  lang: "en-us",
};
 
export async function GET() {
  const allPosts = await getPosts();
  const posts = allPosts
    .map(
      (post) => `    <item>
        <title>${post.frontMatter.title}</title>
        <description>${post.frontMatter.description || ""}</description>
        <link>${CONFIG.siteUrl}${post.route}</link>
        <pubDate>${new Date(post.frontMatter.date).toUTCString()}</pubDate>
    </item>`
    )
    .join("\n");
 
  const xml = `<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">
  <channel>
    <title>${CONFIG.title}</title>
    <link>${CONFIG.siteUrl}</link>
    <description>${CONFIG.description}</description>
    <language>${CONFIG.lang}</language>
${posts}
  </channel>
</rss>`;
 
  return new Response(xml, {
    headers: {
      "Content-Type": "application/rss+xml",
    },
  });
}

Step 9: Create Your First Blog Post

Create src/app/posts/my-first-post/page.mdx


---
title: My First Blog Post
date: 2024/01/15
description: Welcome to my new blog built with Next.js and Nextra!
tags: [web development, next.js, blogging]
author: Your Name
---
 
# My First Blog Post
 
Welcome to my new blog! This post demonstrates the power of MDX for creating rich, interactive content.
 
## Features
 
This blog includes:
 
- **MDX Support**: Write JSX directly in your markdown
- **Syntax Highlighting**: Beautiful code blocks
- **Tag System**: Organize posts by topic
- **RSS Feed**: Keep readers updated
- **Search**: Find content quickly
- **Dark Mode**: Easy on the eyes
 
## Code Example
 
Here's a simple React component:
 
```jsx
function HelloWorld() {
  return <h1>Hello, World!</h1>;
}
```
 
## What's Next?
 
Stay tuned for more posts about web development, programming tips, and technology insights!

Step 10: Add Custom Styling

Create src/app/globals.css


/* Override Nextra blog theme for custom styling */
 
/* Make prose content wider on desktop */
@media (min-width: 768px) {
  .x\:prose {
    max-width: 90ch !important; /* Increase from default ~65ch to 90ch */
  }
}
 
/* Custom tag styling */
.nextra-tag {
  @apply px-2 py-1 text-xs bg-gray-100 dark:bg-gray-800 rounded-md hover:bg-gray-200 dark:hover:bg-gray-700 transition-colors;
}
 
.nextra-tag.active {
  @apply bg-blue-100 dark:bg-blue-900 text-blue-800 dark:text-blue-200;
}
 
/* Custom navigation link styling */
.nextra-nav-link {
  @apply px-3 py-2 rounded-md hover:bg-gray-100 dark:hover:bg-gray-800 transition-colors;
}
 
.nextra-nav-link.active {
  @apply bg-gray-100 dark:bg-gray-800 font-medium;
}

Step 11: Run and Deploy

Development


npm run dev

Visit http://localhost:3000 to see your blog!

Build for Production


npm run build
npm start

Deploy to Vercel

Push your code to GitHub
Connect your repository to Vercel
Deploy automatically!

Step 12: Customization Ideas

Add More Features

Newsletter Signup: Integrate with ConvertKit or Mailchimp
Comments: Add Giscus or Disqus comments
Analytics: Google Analytics or Plausible
Image Optimization: Next.js Image component
Reading Progress: Progress bar for long posts
Related Posts: Suggest similar content
Author Pages: Multiple author support
Series: Group related posts

SEO Enhancements


// Add to your layout.jsx
export const metadata = {
  title: {
    default: "Your Blog Name",
    template: "%s | Your Blog Name",
  },
  description: "Your blog description",
  keywords: ["next.js", "blog", "typescript"],
  authors: [{ name: "Your Name" }],
  creator: "Your Name",
  openGraph: {
    type: "website",
    locale: "en_US",
    url: "https://yourdomain.com",
    siteName: "Your Blog Name",
  },
  twitter: {
    card: "summary_large_image",
    creator: "@yourusername",
  },
};

Conclusion

You now have a fully functional blog with:

✅ Modern Next.js 15 + TypeScript setup
✅ Nextra 4 for easy MDX content management
✅ Tag system for content organization
✅ RSS feed for subscribers
✅ Search functionality
✅ Dark/light theme switching
✅ SEO optimization
✅ Mobile-responsive design

Your blog is ready for content creation and can be easily extended with additional features as your needs grow!

Happy blogging! 🚀 To get started, you can copy the content of this post and paste it into Cursor.