Developer Portfolio
A multilingual developer portfolio built with Next.js 16, React 19, and MDX. Zero databases, maximum performance, and excellent Developer Experience.

Developer Portfolio: An architecture based on MDX, i18n, and Next.js 16

A personal portfolio is a developer's ultimate proving ground. Instead of reaching for ready-made WordPress templates or heavy Headless CMS systems, I built an ultra-lightweight application from scratch in Next.js. The project combines a modern tech stack (React 19, App Router) with full internationalization (i18n) and a content system based entirely on Markdown/MDX files.

📋 Project metrics

• Go-live: Early 2026
• Status: Continuous Deployment
• Role: Lead Architect / Developer
• Goal: Create a performant, secure, and maintainable platform to showcase projects, 100% managed via the Git repository.

🚀 Project evolution (Architecture)

1. Content system (MDX): Moving away from databases in favor of next-mdx-remote and frontmatter (gray-matter). Content is parsed at build-time, guaranteeing instant loading.
2. Internationalization (i18n): Implemented next-intl to handle multi-language routing at the App Router level (dynamic /[locale] paths).
3. Design System & Theming: Styling powered by Tailwind CSS (v3) with native light/dark mode toggling via next-themes.
4. Quality & Testing: A rigorous setup using Vitest, React Testing Library, ESLint, and TypeScript, catching bugs well before the build phase.

🎯 Business problem

Presenting developer projects requires a platform that itself serves as proof of the creator's skills. Typical CMS-based portfolios incur database hosting costs, require plugin updates, and often suffer from mediocre performance, which negatively impacts Core Web Vitals and first impressions.

❌ Pain points and operational challenges

• Management overhead: Clicking through CMS panels just to add a short project is a waste of time.
• Language silos: Maintaining consistency between Polish and English versions gets chaotic without a solid i18n mechanism.
• Performance (SEO): Resource loading delays or Client-Side Rendering (CSR) discourage Google bots.

💡 Why it works (engineering approach)

• Git-based CMS: Projects are kept as .mdx files directly in the repo. Adding a new project is just a git push of a text file — total version control and perfect Developer Experience (DX).
• Static & Server Rendering: Leveraging Next.js Server Components (RSC) and pre-rendering generates static HTML. Only the bare minimum of JavaScript is sent to the browser.
• Integrated SEO: Dynamically generated sitemap.ts, robots.ts, and JSON-LD support (schema-dts) allow search engines to deeply understand the portfolio's structure.
• Solid type foundations: Combining TypeScript with frontmatter schema validation using Zod.

📈 Impact on development (ROI from architecture)

An "everything-in-code" approach minimized costs and maximized publishing speed.

"Switching to an MDX and App Router architecture eliminated CMS overhead, granting full control over code and content straight from the IDE."

🛠️ Architecture & tech stack

• Core: Next.js 16.1.1 (App Router, Server Components), React 19
• Language: TypeScript 5 (Strict Mode), Zod schema validation
• Styling: Tailwind CSS 3, PostCSS, Lucide React (icons)
• Content: next-mdx-remote, gray-matter, remark-gfm
• i18n & Meta: next-intl, next-themes, dynamic metadata
• Code Quality: Vitest, React Testing Library, ESLint, Prettier, Dependency Cruiser

🚀 Summary

The current iteration of this portfolio proves that advanced architecture doesn't have to be overcomplicated. Using MDX alongside Next.js 16 provides a powerful, scalable solution that combines the freedom of writing in Markdown with the capabilities of the modern React ecosystem.