Building my portfolio with Next.js and TypeScript

Why I wanted this portfolio to be more than a simple CV site

I wanted this portfolio to do more than list a few projects and contact links. The aim is to build something that shows how I think through software decisions, how I explain technical work, and how my commercial experience connects with the developer roles I am working towards.

The site is aimed at junior software developer, backend developer, full-stack developer and web developer roles. That affects how I have structured it. Instead of making the homepage do everything, I use separate pages for projects, case studies, experience, about, notes and contact.

The homepage gives a quick overview, while the deeper pages give more detail about what I have built, what I have worked on and what I am learning.

Why I chose Next.js, TypeScript and MDX

I chose Next.js because it gives the portfolio a strong base for routing, metadata, static pages, dynamic case studies and full-stack features such as the contact form.

TypeScript helps keep the project easier to manage as it grows. Project data, notes, experience content and shared component props can be typed properly instead of relying on guesswork.

MDX is useful because the case studies and notes need more than plain text. They can include headings, links, code examples, callouts and technical explanations while still being stored as content files.

The main reason for choosing this stack is that it supports the content well. The code matters, but the portfolio also needs to explain my projects and experience clearly.

Keeping content separate from UI

One of the most useful decisions has been separating content from page layouts.

For example, the homepage has its own content file, the project system has project metadata, the experience page uses structured role data, and the notes section uses separate metadata and MDX files.

This makes the site easier to update because I do not need to dig through large page files just to change a sentence, date, tag or project link.

It also makes future updates more predictable. Adding a new note mainly means adding:

• a new MDX file
• a metadata entry
• a route generated from the slug

That is much easier to maintain than hardcoding every card manually.

Implementation evidence in the repository

The portfolio is built with the Next.js App Router, typed content files and MDX-backed pages. The projects page pulls from structured project metadata, while individual case studies use MDX so each write-up can include headings, links, code examples, tables and evidence sections without becoming one large page component.

The contact flow is a full-stack feature rather than a static mail link only. The form validates input on the client and server, sends accepted submissions through an API route, stores them in Supabase and can send a Resend email notification. The browser never writes directly to Supabase.

I also wanted the site to be testable. The repository includes Vitest unit tests for filtering and helpers, Playwright tests for navigation and the contact form, and a GitHub Actions workflow that runs validation on pushes and pull requests. That gives the portfolio a more realistic engineering shape than a purely visual project.

The SEO and accessibility work is handled in code too: route metadata, canonical URL helpers, a sitemap, robots rules, structured page headings and reusable MDX rendering. The about page then gives the personal context behind those technical choices.

Building reusable components first

Before building the main pages, I created reusable components such as buttons, cards, badges, tags, page headers, section headings, callouts and CTA sections.

That helped keep the design consistent. The same card style can support project cards, note cards, experience cards and about page sections. The same tag pattern can be reused for skills, project technologies and note topics.

It is not a huge design system, but it gives the project a cleaner structure and stops the same styling being repeated everywhere.

What I learned from the build process

The biggest thing I have learned is that a portfolio is not just a website. It is also a way to explain my work clearly.

It is not enough for the site to look good. It needs to explain:

• what I built
• why I built it that way
• what constraints I worked with
• what technical decisions I made
• what I learned from the work

I have also learned that file structure matters more as the project grows. At the start, it is easy to put everything into one page file. That works for a while, but it becomes harder to maintain once the homepage, projects, case studies, experience page, notes and contact form are all in place.

What I want to improve next

The main improvements I am focusing on now are expanding the content, refining existing case studies and continuing to improve the overall quality of the portfolio.

As new projects are completed, I plan to add more case studies with stronger technical detail, screenshots, diagrams, API examples and other supporting material where it is useful and appropriate to share. Some commercial work cannot include private screenshots or sensitive data, so those sections will continue to focus on explaining the technical decisions, challenges and outcomes instead.

I also want to keep improving the written content so it remains clear, accurate and useful for employers, recruiters and other developers who visit the site.

Now that the portfolio has been launched, the main advantage is that the structure is already in place. The homepage, projects, case studies, experience page, contact form and notes section can continue to grow without requiring major changes to the site's foundations.