The Engineering Behind a Personal Portfolio

Most people see a personal portfolio as a simple static site. A few pages of text, some project links, and maybe a contact form. But for me, this site is more than just a digital resume. It is a playground for testing new technologies, a showcase of my engineering standards, and a tool for building my personal brand.

When I decided to revamp aftaab.xyz, I didn’t want to just throw together some HTML and CSS. I wanted to build a system that reflected how I approach product development for my clients. I wanted it to be fast, accessible, maintainable, and visually striking. I treated it like a high-stakes production application, and the results have been incredibly rewarding.

In this post, I want to take you behind the scenes and show you the engineering decisions that went into building this site. From the choice of framework to the way I handle content and styling, every detail was carefully considered.

The Core Stack: Next.js and TypeScript

The foundation of the site is Next.js. I chose Next.js because it offers the perfect balance of developer experience and performance. It handles things like server-side rendering, static site generation, and image optimization out of the box, which allows me to focus on building features rather than configuring build tools.

I also used TypeScript throughout the project. I am a big believer in type safety, even for small projects. TypeScript helps me catch errors early, provides better IDE support, and makes the codebase much easier to refactor. It also acts as a form of documentation, making it clear what data structures are expected in each part of the app.

Using a modern stack like this is not just about using the latest and greatest tools. It is about building a foundation that is robust and future-proof. It allows me to easily add new features, like this blog, without having to rewrite large parts of the site.

Content Management with Markdown

For a developer portfolio, content is king. I needed a way to manage my projects, my experience, and my blog posts without having to write a lot of boilerplate code. I decided to use Markdown for all my content.

Markdown is a simple, human-readable format that is perfect for writing long-form content. I use a library called gray-matter to parse the frontmatter of my Markdown files and markdown-it to render the content into HTML. This setup allows me to write my blog posts in my favorite text editor and have them automatically appear on the site.

This approach has several advantages. It keeps my content separate from my code, it makes it easy to version control my writing, and it allows me to use powerful tools like grep to search through my posts. It also means that I don’t need a heavy CMS (Content Management System) that would slow down the site.

// A snippet of the logic used to fetch and parse blog posts
export function getAllBlogs(): BlogPost[] {
  const files = fs.readdirSync(contentDir).filter((f) => f.endsWith('.md'));

  return files.map((fileName) => {
    const filePath = path.join(contentDir, fileName);
    const fileContent = fs.readFileSync(filePath, 'utf8');
    const {data, content} = matter(fileContent);

    return {
      id: data.id,
      slug: slugifyTitle(data.title),
      title: data.title,
      date: data.date,
      description: data.description,
      content,
    };
  });
}

Styling and Design System

For styling, I chose Tailwind CSS. I know that Tailwind is a polarizing topic in the design world, but for me, it is an incredible productivity booster. It allows me to build custom designs quickly without leaving my HTML files. It also ensures that my styling is consistent across the entire site.

I used Tailwind in combination with shadcn/ui, which is a collection of re-usable components built with Radix UI and Tailwind. This allowed me to add complex UI elements like tabs, dialogs, and navigation menus with very little effort. Each component is fully accessible and easy to customize to fit the aesthetic of my brand.

I am particularly proud of the dark mode implementation. I used next-themes to handle the theme switching, which ensures that there is no flash of unstyled content (FOUC) when the page loads. The colors were carefully chosen to be easy on the eyes while still providing enough contrast for readability.

Performance as a Feature

Performance was a top priority for this project. A slow portfolio is a bad first impression. I wanted the site to feel instant, regardless of the user’s device or connection speed.

I leveraged Next.js’s image optimization to ensure that images are served in the most efficient format and size. I also used static site generation (SSG) for as many pages as possible, which means that the HTML is pre-rendered at build time and served from a CDN. This leads to incredibly fast load times and improved SEO.

I also paid close attention to the bundle size. I avoided large libraries and used tree-shaking to ensure that only the code I actually use is sent to the browser. The result is a site that scores nearly perfect on Google’s Lighthouse audits.

Accessibility and Inclusivity

Accessibility is not an afterthought in my work. It is a fundamental requirement. I want my portfolio to be usable by everyone, including people who use screen readers or other assistive technologies.

I used semantic HTML throughout the site and ensured that all interactive elements have proper ARIA labels and focus states. I also tested the site with various accessibility tools to find and fix potential issues.

Building an accessible site is not just about compliance. It is about empathy and professional standards. It shows that I care about all my users and that I have the technical skill to build inclusive products.

The Importance of Motion

While I wanted a clean and minimalist aesthetic, I also wanted the site to feel alive. I used framer-motion to add subtle animations and transitions throughout the site.

These animations are not just for show. They provide feedback to the user and create a sense of continuity as they navigate between pages. I was careful not to overdo it, as too much motion can be distracting or even nauseating for some users. I also ensured that all animations respect the user’s prefers-reduced-motion setting.

// A simple example of a page transition with Framer Motion
export const PageTransition = ({ children }: { children: React.ReactNode }) => (
  <motion.div
    initial={{ opacity: 0, y: 10 }}
    animate={{ opacity: 1, y: 0 }}
    transition={{ duration: 0.4, ease: "easeOut" }}
  >
    {children}
  </motion.div>
);

Continuous Deployment and Maintenance

A portfolio is never truly finished. I am constantly adding new projects, writing new blog posts, and refining the design. To make this process as smooth as possible, I set up a continuous deployment pipeline using Vercel.

Every time I push a change to my GitHub repository, Vercel automatically builds and deploys the new version of the site. This allows me to iterate quickly and get new content out to the world in minutes. It also provides me with preview deployments for every pull request, so I can test my changes in a real environment before they go live.

I also have a suite of automated tests that run on every deployment to ensure that I haven’t introduced any regressions. This gives me the confidence to make changes and improvements without fear of breaking the site.

Why it Matters for My Clients

By treating my portfolio as a production application, I am demonstrating the level of care and expertise that I bring to every client project. I am showing that I don’t just know how to write code, but I know how to build a complete, high-quality product.

My portfolio is a living proof of my skills in frontend development, systems engineering, and product design. It shows that I value performance, accessibility, and maintainability. It is the best way I have of building trust with potential clients before we even have our first conversation.

Conclusion

Building aftaab.xyz has been a labor of love. It has allowed me to express my creativity and my technical values in a way that is uniquely mine. It is a tool that helps me connect with the world and share my work with potential clients and fellow developers.

If you are a developer, I encourage you to take the time to build a portfolio that reflects who you are and what you care about. Don’t just settle for a template. Build something that you are proud of. It is one of the best investments you can make in your career.