This Site's Tech Stack: Next.js 15, MDX, and Full-Stack TypeScript

Every developer portfolio site is also a statement about how you think about software. The technologies you choose, the trade-offs you make, and the level of polish you achieve all communicate something about your engineering values. This post walks through the key technical decisions behind this site and explains why I made each choice.

The short version: Next.js 15 with the App Router for the framework, MDX for content authoring, Tailwind CSS for styling, Hono for the API layer, Drizzle ORM for database access, and Vercel for deployment. The longer version involves a fair amount of opinionated reasoning that I think is worth sharing.

Why MDX Over a CMS

I evaluated several content management approaches before settling on MDX files stored directly in the repository. The alternatives included headless CMS platforms like Sanity and Contentful, database-backed content with a custom admin UI, and plain Markdown without the component extensibility.

MDX won because it gives me the best balance of writing ergonomics, version control, and flexibility. Content lives alongside code, so there is a single source of truth with full Git history. I can write in Markdown for straightforward posts and drop in React components when I need something interactive. There is no external service dependency, no API latency for content fetching, and no CMS-specific lock-in.

// Content loading with frontmatter parsing and type safety
import { compileMDX } from 'next-mdx-remote/rsc'
import { mdxComponents } from '@/components/mdx/mdx-components'
 
interface ProjectFrontmatter {
  title: string
  slug: string
  date: string
  description: string
  category: 'DeFi' | 'Trading Bots' | 'Web Apps' | 'Tools'
  tags: string[]
  featured: boolean
  published: boolean
  liveUrl?: string
  githubUrl?: string
}
 
async function renderProject(source: string) {
  const { content, frontmatter } = await compileMDX<ProjectFrontmatter>({
    source,
    components: mdxComponents,
    options: {
      parseFrontmatter: true,
      mdxOptions: {
        remarkPlugins: [remarkGfm],
        rehypePlugins: [rehypePrism, rehypeSlug],
      },
    },
  })
  return { content, frontmatter }
}

The API Layer: Hono Inside Next.js

For the dynamic features -- the contact form, page view tracking, and any future interactive elements -- I use Hono as the API framework, running as a Next.js route handler. Hono gives me express-like ergonomics with much better TypeScript support and a fraction of the bundle size. It also has excellent middleware for validation, CORS, and rate limiting.

import { Hono } from 'hono'
import { cors } from 'hono/cors'
import { rateLimiter } from '@/lib/rate-limit'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'
 
const api = new Hono().basePath('/api')
 
api.use('*', cors())
 
api.post(
  '/contact',
  rateLimiter({ windowMs: 60_000, max: 3 }),
  zValidator(
    'json',
    z.object({
      name: z.string().min(1).max(100),
      email: z.string().email(),
      message: z.string().min(10).max(2000),
    })
  ),
  async (c) => {
    const { name, email, message } = c.req.valid('json')
    await db.insert(contacts).values({ name, email, message })
    await sendNotificationEmail({ name, email, message })
    return c.json({ success: true }, 201)
  }
)
 
export const GET = api.fetch
export const POST = api.fetch

The database layer uses Drizzle ORM, which provides full type safety from schema definition through query execution. The schema is defined in TypeScript, and Drizzle generates the SQL migrations. This approach keeps the entire stack in a single language with end-to-end type safety.

Styling: Tailwind CSS with a Design System

I use Tailwind CSS with a set of custom design tokens defined in the config. The color palette supports light and dark modes through CSS custom properties, and the typography scale is tuned for readability of long-form technical content. Code blocks use a carefully chosen syntax theme that works well in both light and dark modes.

The component library is built on top of Radix UI primitives via shadcn/ui, which gives me accessible, unstyled components that I can customize with Tailwind. This approach avoids the common problem with component libraries where you spend more time fighting the library's opinions than building your own design.

Performance and Deployment

The site is deployed on Vercel with automatic builds triggered by Git pushes. Pages that can be statically generated are pre-rendered at build time, while dynamic routes use server-side rendering with caching. The MDX compilation happens at request time using React Server Components, which keeps the client bundle lean since the MDX processing code never ships to the browser.

// next.config.ts - Key configuration for MDX and performance
const config: NextConfig = {
  images: {
    formats: ['image/avif', 'image/webp'],
  },
  experimental: {
    optimizePackageImports: ['@radix-ui/react-icons', 'lucide-react'],
  },
}

Core Web Vitals are something I actively monitor and optimize for. The combination of static generation, minimal client JavaScript, optimized fonts and images, and Vercel's edge network results in consistently fast load times regardless of the visitor's location. It is not just vanity metrics -- a fast site is a better reading experience, and the technical content on this blog often attracts readers on slower connections from around the world.