# Learning Next.js the Hard Way: Breaking and Fixing My Own Portfolio

> My first serious Next.js build. It started with fast experimentation, then became a real crash course in architecture, debugging, and owning implementation decisions end to end.

- **Source:** https://ciaranwhiteside.com/projects/learning-nextjs-portfolio
- **Author:** Ciaran Whiteside
- **Updated:** 2026-05-31
- **Topics:** Next.js, React, Tailwind, TypeScript, Framer Motion, Performance
- **Live site:** https://ciaranwhiteside.com

![The ciaranwhiteside.com homepage: the portfolio hero with the oversized "Ciaran Whiteside" wordmark and a Focus summary card.](https://ciaranwhiteside.com/projects/learning-nextjs-portfolio/hero.webp)

*ciaranwhiteside.com — the portfolio itself, built and rebuilt in Next.js.*

---

## Where It Started

I had a clear idea of the outcome, but no mature process. ChatGPT helped speed up early iteration, but the real progress came from understanding each decision and fixing issues directly.

## Getting the Stack Right

- Started on Next.js 13.5.4 and quickly discovered version drift and security concerns
- Migrated to Next.js 14 for stability
- Upgraded again and hit major regressions (routing, layout, hydration)
- Rebuilt key parts of the app with a cleaner structure and tighter control

## What Changed

- Broke large components into smaller, reusable pieces
- Added motion intentionally to improve polish without harming performance
- Implemented consistent light/dark theming with predictable tokens
- Fixed hydration issues by isolating client-only behavior through dynamic imports

## Branding and Presentation

I replaced placeholder assets with a proper logo set, favicon suite, and social preview image so the site looked credible in-browser and when shared.

## What Went Wrong and What I Learned

- AI assistance is powerful, but blind trust creates technical debt
- Early shortcuts often become expensive later
- Repeated break/fix cycles build real engineering intuition

## Outcome

- Fully responsive portfolio with robust theme support
- Cleaner architecture and improved maintainability
- Fast, intentional UI behavior with stronger implementation confidence

## Would I Do It Again?

Yes. It was frustrating at points, but it accelerated my practical front-end and product engineering skills in a meaningful way.