What a web developer
portfolio should include.
A web developer portfolio should lead with three to five live, deployed projects a hiring manager can click and use, each with a link to the running site and a link to clean source on GitHub. For every project, name the stack you built it with, show that it is responsive and works on a phone, and back the "it is fast" claim with a real number such as a Lighthouse or Core Web Vitals score. Because your own portfolio site is itself a work sample, it has to be fast, responsive, and accessible or it argues against you. Below is the full list of what to put in, the terms a recruiter actually searches, and which of the Portfolio designs suit a developer.
The sections a web developer portfolio needs.
A developer is hired on proof they can ship working software, so the portfolio is built around evidence you can click, read, and run. Work through these in order, and read the flagged block twice.
Live, deployed projects
Three to five projects that are actually running on a URL, not a folder of screenshots. A reviewer wants to click through, resize the window, and see the thing respond. A deployed link is the single strongest signal that you finish and ship, so lead with it and make sure every link resolves.
The stack, stated per project
For each project, name what you built it with: HTML5, CSS3, and JavaScript or TypeScript at the base, then the framework such as React, Vue, Next.js, or Astro, styling like Tailwind, any headless CMS, and where it is hosted. A reviewer maps your stack to their stack in seconds, so make it easy to read.
Source on GitHub
Link the repository next to the live site. Reviewers read commit history, folder structure, and a clear README to judge how you actually write and organise code. Pin your strongest repos on your profile and make sure the README explains what the project is and how to run it locally.
Performance and Core Web Vitals
Put numbers on speed. A Lighthouse score, a Largest Contentful Paint figure, or a before and after page-speed win reads as engineering maturity. "Cut LCP from 4.1s to 1.3s by lazy-loading images and trimming the bundle" tells a reviewer you measure and improve, not just build.
Responsive and cross-browser proof
Show the work holds up on a phone, a tablet, and desktop, and across current browsers. If a design came from Figma, note the Figma-to-code accuracy. Responsive layout is table stakes now, so a portfolio that breaks on mobile quietly disqualifies you.
Accessibility work
Call out the WCAG work you did: semantic HTML, keyboard navigation, colour contrast, focus states, and alt text. Accessibility is increasingly a hiring filter, and a candidate who names their a11y practice stands out from one who never mentions it.
Never include: dead links, slow pages, or work you cannot show
Do not link a dead or broken URL, do not display client work you do not have permission to publish, and do not ship a portfolio site that is slow or inaccessible, because that undercuts the exact pitch you are making. A 404 or a five-second load on your own site is read as a live demo of how you build.
Keep credentials out of any embedded code. No API keys, tokens, or connection strings in a public snippet or a public repo. If a project needs a secret to run, use an environment variable and a placeholder, and say so in the README.
Terms a developer recruiter searches.
Recruiters and applicant tracking systems search for specific technologies. If these are true of you, use the exact words, because a system indexes the words you wrote, not the ones you meant.
Paste your resume into the free ATS score checker with a real web developer job posting to see which of these terms the posting uses and your resume is missing.
Which designs suit a developer portfolio.
A developer portfolio is judged on speed and clarity as much as content, so the design should be a fast, image-light project grid. Of the 60 Portfolio designs and 48 resume layouts, these are the shapes that fit.
Pick a design that puts a grid of projects near the top, each card carrying a title, the stack, and two links: live site and repo. Avoid heavy full-bleed image designs that hurt your own load time, because a slow portfolio contradicts the skill you are selling.
Of the 48 resume layouts, choose a single-column one over a two-column design. Multi-column resumes can serialise into a scrambled reading order when a tracking system parses them, which buries the stack keywords a recruiter is searching for.
Order each card so the live demo and the GitHub link sit together and are impossible to miss. A reviewer wants to run it and read it, so make both one click away rather than hidden behind a case-study scroll.
Keep the type clean and the assets light. A reviewer, often another engineer, is scanning fast, and a page that loads instantly and reads clearly is itself the proof. Let the working demos carry the flourish.
Who a developer portfolio is not for.
A portfolio helps most web developers, but not in every situation. Read this before you spend a weekend on it, because sometimes a sharp resume and a strong GitHub do more.
Worth building if you
- +Are a front-end, full-stack, or freelance web developer whose value is easiest to prove by clicking a working site.
- +Are a career changer or bootcamp graduate whose projects carry the weight a job history cannot yet.
- +Freelance or contract and want one link that shows the sites you shipped, the stack, and how to reach you.
- +Want a personal site that doubles as a live performance and accessibility work sample.
Skip it, for now, if you
- −Are a senior developer applying through referrals, where a resume and a GitHub profile usually carry the conversation.
- −Have only client work you cannot show publicly, and no side project you are free to deploy yet.
- −Would ship a slow or broken portfolio under time pressure. A weak site hurts more than no site here.
- −Have a deadline this week. Fix the resume so a tracking system reads your stack, then build the site.
Questions web developers ask.
Straight answers on projects, live demos, and whether the site itself is being judged.
How many projects should a web developer portfolio have?
Three to five is the right range. Enough to show range across different stacks or problem types, few enough that every one is polished and every link works. A reviewer would rather see four strong, deployed projects than ten half-finished ones. Lead with your best, and cut anything that no longer runs.
Should projects be a live demo or a screenshot?
A live, deployed demo, every time. Screenshots prove you can design a mockup; a running URL proves you can ship and host working software. If a project genuinely cannot be public, record a short screen capture, but a clickable link is far stronger and is what a reviewer expects from a web developer.
Does my portfolio site itself get judged?
Yes, more than in most fields. Your portfolio is a live sample of how you build, so reviewers notice if it loads slowly, breaks on mobile, or fails basic accessibility. Run Lighthouse on your own site before you share it, and treat its speed, responsiveness, and a11y as part of the pitch, not the wrapper around it.
What if my client work is behind a login?
You cannot publish work you do not have permission to show, and you cannot expose a client login. Describe your contribution in words, name the stack and the outcome, and link a public rebuild or a side project that demonstrates the same skill. Never paste client credentials or internal URLs to prove the work.
Should I include Lighthouse scores?
If they are strong, yes. A Lighthouse score or a Core Web Vitals figure turns "my site is fast" into a number a reviewer can trust, and a before and after page-speed win shows you measure and improve. Keep the numbers current, since a score you posted a year ago may no longer match the live site.
How should I frame freelance versus employed work?
Label each project clearly: personal, freelance client, or work built on the job. For freelance work, note your role and what you shipped; for employed work, show only what you are allowed to and describe the rest. A reviewer reads honesty about scope as a good sign, so do not imply solo credit for a team build.
Where to go next.
Build the site, test your resume, or read how the paste-a-resume flow works.
Turn your developer
resume into a site.
Paste your resume and Portfolio drafts a fast, project-grid website in about a minute. Live sites and repos linked side by side, a page light enough to load instantly, published to your own domain with TLS handled for you.