CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

# Start development server
pnpm dev

# Build for production
pnpm build

# Type check
pnpm typecheck

# Lint code
pnpm lint

# Generate database migrations
pnpm db:generate

# Apply database migrations
pnpm db:migrate

Environment Setup

Environment variables are strictly type-checked in lib/env.ts. Copy .env.example to .env or .env.local and populate required values.

Key required variables:

DATABASE_URL: PostgreSQL connection string (Neon)
AUTH_SECRET: Random value for authentication encryption
AUTH_GITHUB_CLIENT_ID / AUTH_GITHUB_CLIENT_SECRET: GitHub OAuth App credentials
RESEND_API_KEY / RESEND_TO_EMAIL: For contact form emails
NEXT_PUBLIC_GITHUB_REPO / NEXT_PUBLIC_GITHUB_USERNAME: For projects page

Architecture

Tech Stack

Next.js App Router: Server components with TypeScript
Tailwind CSS v4: Utility-first styling with shadcn/ui components
Drizzle ORM: Type-safe database interactions with Neon PostgreSQL
Better Auth: Authentication with GitHub OAuth
MDX: Enhanced markdown for blog posts with custom plugins

Key Structure

/app: App Router pages and API routes
/components: Feature-organized React components
/lib: Core utilities, configs, and database schema
/notes: MDX blog content files
Database schema: lib/db/schema.ts with users, sessions, comments, and page views

Content & Features

Blog posts (/notes) are MDX files with frontmatter
Comments system with nested threads
Hit counter API (/api/hits)
GitHub projects showcase
Contact form with Vercel BotID protection
RSS/Atom feeds
Theme toggle (dark/light mode)

Development Notes

Always prefer React Server Components over client components
Database operations use Drizzle ORM with Neon's serverless client
MDX processing includes custom remark/rehype plugins configured in next.config.ts
Deployment assumes Vercel with specific environment handling
Strict ESLint and TypeScript configuration enforced

2.1 KiB Raw Permalink Blame History