danabra.mov
my blog https://overreacted.io
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5## Development Commands
6
7```bash
8# Start development server
9npm run dev
10
11# Build static site for production
12npm run build
13
14# Start production server (after build)
15npm start
16
17# Lint the codebase
18npm run lint
19
20# Apply patches after dependency changes
21npm run postinstall
22```
23
24## Architecture Overview
25
26**Static Blog with Next.js App Router**: This is Dan Abramov's personal blog built as a static site using Next.js 15 with the App Router and React 19. The site exports to static files (`output: "export"`).
27
28**Blog Post Structure**: Posts are stored as markdown files in `/public/[slug]/index.md` with frontmatter containing metadata (title, date, spoiler, youtube). Each post directory can contain:
29- `index.md` - The main post content
30- `components.js` - Post-specific React components and optional `Wrapper` component
31- Asset files (images, etc.)
32
33**Content Processing Pipeline**:
341. `app/posts.js` reads all post directories from `/public/`
352. Uses `gray-matter` to parse frontmatter from markdown files
363. Posts are sorted by date (newest first)
374. Individual posts are rendered via `app/[slug]/page.js` using `next-mdx-remote-client`
38
39**MDX Processing**: Posts support advanced MDX features:
40- JavaScript code blocks with `eval` meta execute and render inline (see `app/[slug]/mdx.js`)
41- Post-specific components can be imported from `components.js` files
42- Syntax highlighting via Shiki with "Overnight Slumber" theme
43- Auto-linking headings, GFM support, smart quotes
44
45**Routing**:
46- `/` - Home page listing all posts (`app/page.js`)
47- `/[slug]/` - Individual post pages (`app/[slug]/page.js`)
48- `/atom.xml` and `/rss.xml` - Generated feeds (`app/atom.xml/route.js`, `app/rss.xml/route.js`)
49
50**Styling**: Uses Tailwind CSS with custom CSS variables for theming (`--bg`, `--text`, `--title`, etc.). Post titles have dynamic color-coding based on post age using `colorjs.io`.
51
52**Static Generation**: All pages are pre-generated at build time. Post pages use `generateStaticParams()` to create routes for all post directories.
53
54## Key Files
55
56- `app/posts.js` - Core post discovery and feed generation logic
57- `app/[slug]/page.js` - Individual post rendering with MDX processing
58- `app/[slug]/mdx.js` - Custom remark plugin for executable code blocks
59- `next.config.js` - Static export configuration
60- `public/[slug]/index.md` - Post content files with frontmatter
61- `public/[slug]/components.js` - Optional post-specific React components
62
63## Commit Messages
64
65Write commit messages and PR descriptions as a humble but experienced engineer would. Keep it casual, avoid listicles, briefly describe what we're doing and highlight non-obvious implementation choices but don't overthink it.
66
67Don't embarrass me with robot speak, marketing buzzwords, or vague fluff. You're not writing a fucking pamphlet. Just leave a meaningful trace so someone can understand the choices later. Assume the reader is able to follow the code perfectly fine.