Frontend Framework and Runtime
| Layer | Technology | Version | Purpose | |---|---|---|---| | Framework | Next.js | 14.x | React framework with App Router and static export | | Runtime | React | 18.x | UI library and component system | | Language | TypeScript | 5.x | Type-safe development and IDE support | | DOM | React DOM | 18.x | DOM rendering and reconciliation |
Styling and Layout
| Technology | Version | Purpose | |---|---|---| | Tailwind CSS | 3.x | Utility-first CSS framework | | Tailwind Typography | 0.5.x | Prose styling for MDX content | | PostCSS | 8.x | CSS processing and vendor prefixes | | clsx | 2.x | Conditional className composition |
Components and UI
| Technology | Version | Purpose | |---|---|---| | shadcn/ui | latest | Component primitives (buttons, cards, dialogs, etc.) | | Radix UI | 1.x | Headless component primitives (underlying shadcn) | | Custom components | local | Project-specific composite components |
Content Processing
| Technology | Version | Purpose | |---|---|---| | MDX | 3.x | JSX in Markdown for rich content | | @mdx-js/mdx | 3.x | MDX compiler and runtime | | gray-matter | 4.x | YAML frontmatter parser | | remark | 14.x | Markdown processor plugins | | rehype | 12.x | HTML processor for MDX |
Data Validation and Type Safety
| Technology | Version | Purpose | |---|---|---| | Zod | 3.x | Schema validation and runtime type inference | | TypeScript | 5.x | Static type checking |
Build and Development
| Technology | Version | Purpose | |---|---|---| | esbuild | latest | Fast JavaScript bundler (Next.js internal) | | Webpack | 5.x | Module bundler (Next.js internal) | | npm | 9.x+ | Package management | | Node.js | 18.x+ | JavaScript runtime |
Code Quality
| Tool | Purpose | |---|---| | ESLint | Code linting and rules | | Prettier | Code formatting | | TypeScript strict mode | Type safety | | Zod runtime validation | Data safety |
Deployment Infrastructure
| Service | Provider | Purpose | |---|---|---| | Static hosting | Cloudflare Pages | Edge CDN for static files | | CI/CD | GitHub Actions | Automated builds and deployments | | Source control | GitHub | Code repository and version control | | Artifact storage | Cloudflare KV | Optional caching and data store |
Development Tools
| Tool | Version | Purpose | |---|---|---| | VS Code | latest | Recommended IDE | | ESLint extension | latest | Real-time linting | | Prettier extension | latest | Code formatting on save | | Thunder Client / Postman | - | API testing (if APIs added) |
Testing and Validation (Optional)
| Framework | Purpose | |---|---| | Jest | Unit and integration testing | | React Testing Library | Component testing | | Playwright | End-to-end testing |
Performance and Monitoring (Optional)
| Service | Purpose | |---|---| | Cloudflare Analytics | Page views and performance | | Web Vitals | Core metrics monitoring | | Sentry | Error tracking and reporting |
Architecture Decision Rationale
Why Next.js? Modern React framework with excellent static export capabilities, file-based routing, built-in optimization, and large ecosystem.
Why Tailwind CSS? Utility-first approach ensures consistent spacing, colors, and responsive design without custom CSS overhead.
Why shadcn/ui? High-quality component primitives, fully customizable, no vendor lock-in, copy-paste components.
Why Zod? TypeScript-first schema validation at runtime, catches data errors before render, small bundle size.
Why MDX? Markdown readability with React component power, perfect for technical documentation.
Why Cloudflare Pages? Fast edge deployment, free tier, zero-config, perfect for static content with no server needed.