I shipped my developer portfolio on GitHub Pages with Next.js static export

MEHTAB RIAZ — Sun, 19 Apr 2026 19:17:55 +0000

I recently polished and open-sourced my personal portfolio: a Next.js site with JSON-driven content, static export, and GitHub Actions deploying to GitHub Pages—no server, no API routes at runtime.

If you’re comparing stacks for a portfolio or fighting subpath deploys (username.github.io/repo/), this might save you a few rabbit holes.

Live site & repo

Live: mehtabriaz.github.io/portfolio
Source: github.com/MehtabRiaz/portfolio

What it is

A single-page style home with hero, featured work, about, technical stack, and experience, plus extra routes for projects (GitHub API at build time) and articles (Medium RSS via rss2json, also at build time). Most copy and structure live under content/ as JSON, so updates don’t always mean digging through JSX.

Stack in practice:

Next.js (Pages Router), React, Sass
Font Awesome free icons (with a small util to map old Pro-style prefixes to free solid)
Framer Motion for motion where it helps
Jest + Testing Library for a few unit tests

Why static export + GitHub Pages

I wanted:

Free hosting tied to the repo
Predictable URLs for a project site under a subpath
No need to run Node in production—just static files after next build

next.config.js uses output: 'export' so the app becomes plain HTML/JS/CSS in out/. GitHub Pages serves that output from the workflow in .github/workflows/deploy-github-pages.yml.

The annoying part of project pages is the /portfolio/ base path: assets, favicons, manifests, and client-side public URLs must stay consistent. The repo uses basePath / assetPrefix derived from the GitHub repo name in CI, plus a small publicPath() helper so links to public/ files work both locally (/) and on Pages (/portfolio/).

Content model (quick mental model)

Rough map (details in the README):

Area	Where it lives
Settings / GitHub username for APIs	`content/_settings.json`
Hero & page colors	`content/index/hero.json`, `content/index/_colors.json`
Featured projects	`content/projects/featured.json`
Technical section	`content/index/technical.json`
Experience	`content/index/experience.json`
Footer	`content/footer.json`

That split kept the site maintainable as I iterated on copy and featured work.

Things I’d tell my past self

Static export means no pages/api in the classic sense—anything dynamic either runs at build time (getStaticProps + fetch) or moves to an external service.
images.unoptimized is the usual tradeoff for static hosting without an image CDN.
Subpath deploys are solvable but tedious: manifest icons, document head, and any hardcoded /foo paths will bite you until everything goes through your path helper or Next’s basePath.
Favicons: SVG favicons are great, but external images inside SVG favicons are unreliable in Chromium; inlining the bitmap (e.g. data URI) fixed “blank tab icon” for me.

Try it locally


bash
git clone https://github.com/MehtabRiaz/portfolio.git
cd portfolio
npm install
npm run dev

Hello DEV — I'm Mehtab Riaz, and I'm excited to join this community

MEHTAB RIAZ — Sat, 18 Apr 2026 12:53:26 +0000

I'm a software developer who cares about clear, reliable, and useful products. Day to day, I work across the stack with a strong focus on maintainable code, solid interfaces, and performance—the kind of details that keep software pleasant to ship and to live with after launch.

Lately, a lot of my work lives in the JavaScript / TypeScript ecosystem (React, Next.js, modern tooling). I like turning messy problems into something shippable: from sketching an approach, to implementation, to tightening the rough edges before release.

What I do

Full-stack / product-style development — features end to end, not just isolated components
Frontend engineering — React, responsive UI, and performance-minded builds
APIs and backend integration — pragmatic design, sensible error handling, security basics done right
Quality and iteration — refactoring when it pays off, profiling when something feels slow, tests where they earn their keep
Learning in public — writing short notes, documenting what I build, and sharing what I learn along the way

What I'm building now

Right now, I'm especially focused on:
Shipping production-ready web experiences (fast, accessible, maintainable)
Next.js and React patterns that scale with the codebase—not just the first demo
Sharpening system design and architecture intuition through real projects
Open source and portfolio work that doubles as a playground for b etter engineering habits

Why I'm here on DEV

I joined DEV to:

Share what I'm building and how I think about tradeoffs
Document setups, bugs, and wins so my future self (and others) can reuse them
Learn from people who've already solved the problems I'm hitting
C onnect with other developers who care about craft, not just hype

Let's connect

I'm always open to:

Collaboration on web projects and small open-source ideas
Technical discussions — frontend, backend, DX, and everything in between
Feedback on my posts and projects—constructive critique is welcome

If you want to follow along, you can find me here:

GitHub: [edit — add your profile URL, e.g. https://github.com/mehtab-riaz]
Portfolio / site: [wip]
LinkedIn: [https://linkedin.com/in/mehtab-riaz/] I believe in building, sharing, and improving a little every week. Thanks for reading—I'm glad to be here, and I hope we can learn from each other.

Forem: MEHTAB RIAZ