A good developer portfolio shows two to four deep projects, each explaining the problem, your specific role, the engineering decisions you made, and the measurable result. It presents your best GitHub work as curated case studies instead of dumping every repo, links to a clean resume, and lives on your own custom domain so recruiters can actually find it. The engineers who get interviews write about impact and trade-offs, not a list of frameworks they have touched.
The mindset
A reviewer is skimming for signal, not counting repos
A hiring engineer or recruiter opens your portfolio with a stopwatch running. They are not going to read every project, clone a repo, or scroll a contribution graph. They are hunting for one thing: evidence that you can own a hard problem end to end and make sound decisions under real constraints. Everything on the page either supplies that signal or dilutes it.
This is why the wall-of-repos approach fails. Twenty half-finished side projects do not read as productivity, they read as noise, and they force the reviewer to do the filtering you should have done for them. The engineers who get callbacks make a ruthless cut: they pick the two to four projects that best prove they can ship, and they let everything else live quietly on GitHub for the curious.
The rest of this playbook is built on that single idea. Fewer things, explained deeply. Every section below is about choosing what to show and then showing it in the way a busy technical reviewer actually reads.
The project
How to write one project that lands
Every strong developer portfolio project answers the same four questions in this order. Do it for each project and a reviewer gets the full story in under a minute.
State the problem in plain language.
Open with what was broken or missing and who it hurt. "The checkout flow timed out under load and dropped 8 percent of orders" is a problem. "A full-stack e-commerce app" is a category. A reviewer needs the stakes before they care about the solution.
Name your specific role.
If it was a team project, say exactly what was yours. "I owned the payments service and the retry queue" is worth more than a vague "we built." Reviewers are evaluating you, not the group, so draw the line clearly and honestly.
Show the decisions and trade-offs.
This is the part that separates a junior from a senior portfolio. Explain one or two real forks in the road: why you chose a queue over cron, why you denormalized that table, what you gave up. Decisions prove judgment, and judgment is what they are actually buying.
End with the measurable result.
Close on the outcome with a number: latency cut, cost saved, users served, error rate dropped. If you truly have no metric, describe the concrete before and after. A result makes the whole story land and gives the reviewer the line they will repeat to the hiring committee.
The GitHub problem
Present GitHub, do not dump it
Linking your raw GitHub profile and hoping a reviewer explores it is the most common mistake in developer portfolios. A profile page is a firehose: forks, dotfiles, abandoned experiments, and one or two things you are genuinely proud of, all weighted equally. You are asking a busy person to pan for gold. Most will not, and the ones who do may land on your weakest repo first.
Do the curation yourself. Pin your three or four best repositories on your GitHub profile so the top of the page is your strongest work. For each one, make sure the README opens with what the project does, why it exists, and how to run it, because for a lot of reviewers the README is the whole review. Then, on your portfolio, link directly to those specific repos from the matching case study, not to the profile root.
The distinction is curation versus a data dump. A dump says "here is everything, you sort it out." Curation says "here are the four things I want you to judge me on, and here is why each one matters." The second one respects the reviewer's time, and respecting their time is itself a signal about how you work.
By discipline
What to show depending on what you build
The four-question structure is universal, but the proof that matters shifts with your specialty. Show the artifact your reviewers actually care about.
Frontend
Show the thing running
A live, deployed demo beats every screenshot. Pair it with the accessibility, performance, or state-management decisions you made, and a note on how you kept the bundle honest. Reviewers want to see it work, then see that you sweated the details.
Backend
Show the shape of the system
A simple architecture sketch, the data model, and how you handled load, retries, and failure. An API you can point at, or a clear diagram of the services, tells a backend reviewer more than any amount of prose about frameworks.
ML
Show the problem and the evaluation
Lead with the task and the metric you moved, not the model zoo. Explain the data, the baseline you beat, and how you measured it. An honest evaluation section reads as far more senior than a claim that you used the newest architecture.
Infra and platform
Show reliability and cost
Pipelines, deploy story, observability, and the number that went down: incident count, build time, cloud spend. Platform work is invisible when it goes right, so make the impact explicit with before and after.
Mobile
Show the flow and the constraints
A short clip of the core flow, plus the platform constraints you worked within: offline behavior, battery, cold-start time. Reviewers want proof you can ship a real app to a real store, not a tutorial clone.
Early career
Show one thing finished
You do not need ten projects. One project taken all the way to shipped, documented, and reflected on beats a pile of half-done starts. Depth is available to you on day one, and it is what distinguishes a strong junior portfolio.
The writing
Write about impact, not your stack
The fastest way to sound junior is to lead with a list of technologies. A tag cloud of twenty frameworks tells a reviewer nothing about whether you can use any of them well, and it flattens the one project you are proud of into the same visual weight as a weekend tutorial. Tools are table stakes. What you did with them is the story.
Rewrite every line that names a tool to instead name an outcome. "Used React, Node, PostgreSQL, and Redis" becomes "cut the dashboard's p95 load time from 3.2 seconds to under 900 milliseconds by caching the expensive aggregate queries." The second version still tells the reviewer you know Redis, but it also tells them you understand why you reached for it and that it worked. Put the stack in a small, honest line at the end of each case study for the reviewers who scan for it, and keep it out of the headline.
A useful test: read each sentence and ask whether a reviewer could argue with it. "Familiar with distributed systems" is unfalsifiable filler. "Designed an idempotent retry queue that survived a regional outage without duplicate charges" is a claim you can stand behind, and claims you can stand behind are exactly what get you to the interview.
The setup
The engineer stack versus the usual pile of tools
Most developer portfolios stall because the setup is a side project of its own. Here is the difference between assembling it by hand and having it in one place.
| Capability | Folio | Hand-rolled setup |
|---|---|---|
| The site | Premium themes built for engineers, ready to fill with case studies | A static-site generator you configure, style, and maintain yourself |
| Resume | An ATS-ready software engineer resume from the same profile, exported to clean PDF and DOCX | A separate document that drifts out of sync with the portfolio |
| AI help | A first draft from your own profile using a leading AI model, kept as structured content you edit, approve, and export | Paste your work history into a third-party chatbot and hope |
| Custom domain | Connect yourname.dev, certificate issued for you automatically | A registrar, DNS, and TLS you wire up and renew by hand |
| Getting found | Titles, meta, sitemap, JSON-LD, and IndexNow submission built in | Manual markup and a search console you remember to check |
| Automation | A read and write developer API plus an MCP server so assistants can update your portfolio | No API surface, so every update is a manual edit |
The setup is not the achievement. Shipping the case studies is. Fewer moving parts means the portfolio goes live instead of staying a branch you never merge.
The finish
Make it findable and let it work while you sleep
A portfolio recruiters cannot find is a private repo. Once the case studies are written, put the site on your own custom domain, because yourname.dev is an asset you own and a signal that you invested in yourself before asking anyone to invest in you. A platform subdomain hands every backlink and every ranking signal to the platform instead of to you.
Then make sure it is actually indexable: a page title that leads with what you build, a description that reuses your one-line pitch, a sitemap, and structured data so search engines understand the page. When a recruiter searches your name, or searches for the exact stack you specialize in, the goal is that your own site is the first result rather than a scraped profile you do not control. A builder that generates the SEO and submits your URL for you turns that from a project into a checkbox.
The last piece is to keep the whole thing wired together. Link a clean, ATS-ready resume from the portfolio so a reviewer is one click from the paperwork, and generated from the same profile so the two never contradict each other. With Folio, the portfolio, the AI resume, the AI drafting, the custom domain, and a developer API that lets automations keep it current all live in one place. Write the case studies once, publish on a domain you own, and let the page do the reaching out for you.
Frequently asked questions
What should a developer portfolio include?
Two to four deep projects, each with the problem, your specific role, the engineering decisions and trade-offs you made, and a measurable result. Add a curated view of your best GitHub work, a clean linked resume, and a short about section. Skip the wall of repos and the tag cloud of frameworks.
How many projects should be on a developer portfolio?
Two to four, done deeply, beats a long list. A reviewer is skimming for signal, not counting repositories, so a few projects that each show how you think will outperform twenty that nobody opens. Even early in your career, one finished and well-documented project is stronger than many unfinished starts.
How do I show GitHub on my portfolio without dumping every repo?
Pin your three or four best repositories so your strongest work sits at the top of your profile, and make sure each README explains what the project does, why it exists, and how to run it. On your portfolio, link directly to those specific repos from the matching case study rather than to your profile root.
Should I list my tech stack on my developer portfolio?
Yes, but not in the headline. Lead each project with the impact and the decisions, then put a short, honest stack line at the end for reviewers who scan for it. "Cut p95 latency 40 percent by caching the aggregate queries" proves you know the tool better than naming ten technologies ever could.
Do I need a custom domain for a developer portfolio?
Yes. A personal domain like yourname.dev is an asset you own, it reads as a signal of seriousness, and it is the foundation of getting found when a recruiter searches your name or your specialty. A platform subdomain hands every backlink and ranking signal to the platform instead of to you.