A developer portfolio website needs five things: one sentence saying what you build and for whom, three to six projects with live links, a line on what was hard in each, a way to contact you that works in one click, and whether you are available right now. Everything else is optional, and most of it is actively in the way.
Portfolio advice usually goes the other direction and adds things: a skills section, an animated hero, a blog, a testimonials carousel. Each addition pushes the projects further down the page, and the projects are the only part a client came for. This post is about the page itself. If you do not have projects to put on it yet, start with building a portfolio with no experience.
Who reads it, and how
The person reading your portfolio site is usually not browsing. Someone sent them a link, or they found your name next to something you built, and they want to answer one question: can this person do my thing?
They will often be on a phone. They will look at the top of the page, scroll once, open one project, and decide. Design the page for that visit, not for a recruiter reading every word on a desktop.
The top of the page
The first screen should say who you are, what you build, and for whom, in plain words. That is one sentence, not a tagline.
I build iOS and Android apps for small businesses that need bookings and payments. Based in Lahore, working with clients in the UK and US.
Compare that with "Passionate full-stack developer crafting digital experiences". The second one could be anyone. The first tells a café owner with a booking problem that they are in the right place, and tells everyone else to keep looking, which is also useful.
Under it: your name, a real photo, your time zone, and a link straight to your best project. A client should be able to reach the work in one tap.
Projects: the part that does the work
Three to six. Best first, because many people only open the first one. For each, the same short structure:
| Field | Example |
|---|---|
| Name and one line | Tablecall: table reservations for independent restaurants |
| Live link | The real domain or the store listing, not a preview URL |
| Your role | Built it alone, or "backend and payments, in a team of three" |
| One hard thing | "Double bookings when two staff edit the same slot offline" |
| Stack, in one line | Flutter, Supabase, Stripe |
The "one hard thing" line is what separates a portfolio from a list of links. Anyone can say they built an app. Very few people describe a real problem they met in it, and a client can tell the difference immediately.
If a project deserves more than five lines, give it its own page and write it properly. How to write a portfolio case study covers that format.
What to cut
Most portfolio sites are improved by deleting things. Candidates:
- Skill bars and percentages. "React 85%" means nothing and invites the question of what the other 15% is.
- A wall of technology logos. Name the stack inside each project instead, where it is evidence rather than decoration.
- Adjectives about yourself. Passionate, detail-oriented, results-driven. Show it in the projects or leave it out.
- Unfinished work. "Coming soon" sections and projects with no live link. A finished small thing beats an unfinished large one.
- A blog you stopped writing. A last post from two years ago reads as a last sign of life. Either keep it going or take it down.
- Heavy animation and loaders. If the page takes several seconds to show anything on a phone, the client has already formed an opinion about your work.
- Testimonials you cannot attribute. A quote from "J., startup founder" convinces nobody. A named person with a link does.
Contact and availability
Put a plain email address on the page, as text someone can copy. Contact forms fail silently more often than people think, and a client who sends a message into a broken form just assumes you did not reply.
Then say whether you are available, and for what:
- Available from a date, or fully booked until one.
- The kind of work you want: new builds, fixes, ongoing work.
- The smallest engagement you take, if you have one.
That last line saves both sides a conversation. It filters out work you would decline anyway, and it tells a serious client you have thought about how you work.
The technical details clients notice
Clients rarely inspect your code. They do notice, without being able to say why:
- Your own domain. yourname.com, not a free subdomain. It costs about the price of lunch per year.
- It works on a phone. Open it on yours, on mobile data, before you send the link to anyone.
- It loads quickly. A portfolio site is mostly text and a few images. There is no reason for it to be slow.
- Your name is in the page title. When someone hears your name and searches it, this page should be what they find.
- Nothing is broken. No console errors, no dead links, no placeholder text from a template.
If you are a web developer, the site itself is also a sample of your work, so these matter twice. If you build mobile apps or backends, a simple, fast, plain page is fine. Nobody expects a backend developer to win a design award; they expect the work to be easy to find.
One page is usually enough
For most freelancers, one page with the sections above does the job: the sentence, the projects, the contact details, the availability. Add separate case study pages only for the projects that have a story worth telling.
Where else you show up matters too. Clients will look you up in more than one place, so use the same name, photo and links everywhere: your site, your GitHub profile, and any directory you list yourself in. Consistency is a small signal, but it is one of the few a stranger can check in a minute.