Loading Content ...
Project
Building My NextJs Career Portfolio
A pragmatic rebuild of my portfolio — built for recruiters, respected by engineers, and maintainable for a solo dev. This post explains the problems I saw, the golden technical decisions I made, constraints I worked under, measurable results, and lessons learned.
Overview
CHALLENGES
Most personal portfolios I reviewed suffer from three recurring issues.
- Recruiter-hostile: long scrolling homepages, unclear role/value, too many visuals but no quick answer to “Can they do the job?”
- Depth hidden behind visuals: designers build beautiful pages but bury decision-making and technical depth—hard for hiring engineers to assess competency.
- No explanation of trade-offs: projects are shown as polished thumbnails; nothing explains why a particular architecture or tooling choice was made.
GOAL
- Skimmable for non-tech: short role + impact headline, clear CTA (resume / contact).
- Deep for engineers: technical decision sections, architecture diagrams, code snippets (with short explanations).
- Fast, accessible, maintainable: Lighthouse-friendly, keyboard-accessible, and easy to update as projects & skills evolve.
Strategy
Key Decision 1
TypeScript (TS)
âś… Pros
- Early error detection
- Catches bugs at compile time before they reach production.
- Excellent developer experience
- Better autocomplete, refactoring, and self-documenting code.
- Scales well
- Easier to maintain large Next.js apps with multiple developers.
❌ Cons
- Initial learning curve
- Requires understanding types, generics, and interfaces.
- Slightly more code
- Types add verbosity, especially early on.
- Build-time overhead
- Type checking can slow builds in very large projects.
JavaScript (JS)
âś… Pros
- Faster to start
- No type setup or configuration; ideal for quick prototypes or small apps.
- Simpler learning curve
- Easier for beginners or teams unfamiliar with static typing.
- Less boilerplate
- Code is often shorter without type definitions.
❌ Cons
- More runtime errors
- Type-related bugs (undefined, wrong shapes, etc.) are only caught at runtime.
- Harder to scale
- Large codebases become harder to maintain without type safety.
- Weaker IDE support
- Autocomplete and refactoring are less reliable compared to TypeScript.
Winner: Typescript
The long-term benefits and developer experience makes it a clear winner for a project / product that I would intend to maintain for a while
Architecture
Key Decision 2
App Router vs Page Router
If you’ve been working with Next.js, you’ve probably heard of two main approaches: the Pages Router and the newer App Router.
App Router (/app)
âś… Pros
- Better data fetching & performance
- Built-in Server Components, streaming, and granular caching (
fetch,revalidate).
- Built-in Server Components, streaming, and granular caching (
- Improved layouts
- Nested layouts and shared UI without re-rendering the entire page.
- Future-proof
- All new Next.js features ship here first.
❌ Cons
- Steeper learning curve
- Concepts like Server vs Client Components can be confusing.
- More conventions
- Requires understanding file-based patterns (
layout.tsx,loading.tsx,error.tsx).
- Requires understanding file-based patterns (
- Ecosystem mismatch
- Some older libraries expect Pages Router patterns (e.g.,
getServerSideProps).
- Some older libraries expect Pages Router patterns (e.g.,
Pages Router (/pages)
âś… Pros
- Simple and familiar
- Straightforward mental model using
getStaticProps,getServerSideProps.
- Straightforward mental model using
- Mature ecosystem
- Works seamlessly with most libraries and tutorials.
- Lower cognitive overhead
- Easier for small apps or teams new to Next.js.
❌ Cons
- Less flexible layouts
- Global layouts require workarounds (
_app.tsx,_document.tsx).
- Global layouts require workarounds (
- Less performant by default
- No Server Components or streaming.
- Not future-focused
- Feature development is centered on App Router.
Winner: App Router
While Pages Router has been around for a while and is super reliable.
The App Router is designed to handle things like reusable layouts and deeply nested pages. Which helps with folder organization and separation of concern which we will touch on later.
Project Structure
Key Decision 3
Differences in Top-level folder structure & Co-location
| Use Top-Level Folder when… | Use Co-location when… |
|---|---|
| Code is reused across many routes/features | Code is used by one route or feature |
| Component is part of a design system (Button, Modal) | Component is tightly coupled to a page |
| Logic is generic (auth, fetchers, formatters) | Logic is domain-specific |
| You want a stable public API for imports | You want easy deletion/refactoring |
| File would make sense in another app |
The Tools
Key Decision 4
A CSS framework is a pre-written library of Cascading Style Sheets (CSS) code that provides a foundation of ready-made styles and components to streamline web development.
CSS frameworks generally fall into different categories, each with its own approach:
- Component-Based Frameworks: These provide pre-styled, ready-to-use UI components (e.g., navigation bars, forms, modals) that you can drop into your project. They are great for rapid prototyping but can lead to a uniform look if not customized.
- Utility-First Frameworks: These offer low-level utility classes that perform a single function (e.g.,
text-align-center,bg-blue-500). Developers compose these classes directly in HTML to build completely custom designs, offering maximum flexibility.
| Aspect | Tailwind CSS | Bootstrap |
|---|---|---|
| Design philosophy | Utility-first (compose styles in markup) | Component-first (prebuilt UI components) |
| Styling control | Pixel-level, fully custom | Opinionated, follows Bootstrap’s design |
| Learning curve | Steeper at first (many utilities) | Easier initially (ready-made components) |
| Design consistency | Enforced via config (theme tokens) | Enforced via Bootstrap defaults |
| Custom designs | Excellent (no fighting the framework) | Can be harder (overriding styles) |
CONTENT MANAGEMENT
Key Decision 5
| Aspect | MDX | CMS |
|---|---|---|
| What it is | Markdown + JSX in code | Content management system (UI + backend) |
| Who edits content | Edited by Developers | Edited by Non-dev |
| Content location | In the codebase (Git) | In a database (cloud or self-hosted) |
| Workflow | Git-based (PRs, reviews) | UI-based (forms, publish buttons) |
| Custom components |
Constraints
Building this project was not without it’s constraints
Holding a full time job unrelated to web development and building this meant that this entire side-project had to be:
- Time-boxed: each feature must be buildable in small increments (1–3 days).
- Evolvable: content & structure must be trivially editable as projects & skills change.
- No to Low cost (optional): design to run locally or on free hosts (Vercel Hobby, Netlify free) if possible.
SCORES AND METRICS
Results
After Deployment, I’ve ran some loading tests via Google’s Lighthouse Test.
If you’re building for the modern web, Google Lighthouse is your primary diagnostic tool. It is an open-source, automated tool designed to improve the quality of web pages. When you run a Lighthouse audit, it simulates a mobile or desktop user visiting your site and provides a report card across five key categories: Performance, Accessibility, Best Practices, SEO, and Progressive Web App (PWA).
Lighthouse doesn't just give you a random number; it calculates your score based on several specific "Core Web Vitals." Here are the three most common culprits behind low scores and how to fix them.
1. Largest Contentful Paint (LCP)
What it is: Measures loading performance. It marks the point in the page load timeline when the largest image or text block becomes visible.
- The Problem: Large, unoptimized hero images, slow server response times (TTFB), or render-blocking JavaScript.
- The Fix: * Use the
priorityattribute on your LCP image in Next.js.- Serve images in modern formats like AVIF or WebP.
- Implement Streaming SSR to send the header of the page before the data-heavy sections are ready.
2. Cumulative Layout Shift (CLS)
What it is: Measures visual stability. Have you ever tried to click a link, but the page suddenly shifted and you clicked an ad instead? That is a high CLS.
- The Problem: Images without defined dimensions, ads that "pop in," or font swaps that change text size after loading.
- The Fix: * Always set a
widthandheight(or aspect ratio) for images and video elements.- Use Skeletons or reserved-height containers (e.g.,
min-h-[700px]) for content that loads asynchronously.
- Use Skeletons or reserved-height containers (e.g.,
3. Total Blocking Time (TBT)
What it is: Measures interactivity. It quantifies how long the main thread was "blocked" by JavaScript, preventing the user from clicking buttons or scrolling smoothly.
- The Problem: Massive JavaScript bundles, complex animations, or heavy third-party scripts (like trackers or chat widgets).
- The Fix: * Code Splitting: Only load the JavaScript needed for the current page.
- Dynamic Imports: Use
next/dynamicto load heavy components only when they are needed. - Web Workers: Move complex calculations off the main thread.
- Dynamic Imports: Use
My Results
Lighthouse scores of 80-90+% on both Desktop and Mobile (Average of 5 tests per page)
Lessons learnt
What I’d change: remove or prune excessive blog posts or long-form content that gets no traffic — favor high-signal case studies. (However, this would only be after I measure web analytics traffic on a later stage)
What I kept intentionally simple: certification list and concise project summaries — avoid turning the portfolio into an aggregator/scraper of every accomplishment. I had initially wanted to scrape all my certifications however with the frequency of site updates versus my own accreditations. I quickly realized that RPA was a tarpit/honeypot that was not worth the time-cost benefit.