Show three to five projects, chosen for the job you want next rather than for how impressive they sounded when you started them. The strongest mix is one thing real people use, one project that goes deep on a hard problem, and one built in the stack of the roles you're applying for. Give each a short write-up covering the problem, your role, the stack, the decisions you made and what happened, then link the code and a working demo.
Everything else, from the layout to the about page, matters less than those choices. If you want the site around them drafted quickly, there's a portfolio builder set up for software engineers, covered at the end.
What a reviewer is actually checking
A hiring manager or a senior engineer on the interview loop opens your portfolio with a few questions in mind:
- Can this person finish things and put them in front of users?
- Can they explain why they built something one way and not another?
- Will they be comfortable in a codebase like ours?
A portfolio gives the reviewer evidence and, more usefully, something to ask you about. A project with a clear trade-off in its write-up ("I picked Postgres for the queue instead of Redis because...") turns into a twenty-minute conversation you're well prepared for. A project with only a screenshot and a stack list gives them nothing.
So judge every candidate project by one test: what question would a reviewer ask after seeing this, and do you want to answer it?
Pick projects by the signal they send
Different projects prove different things. Sort what you have with this table.
| Project type | What it signals | Keep it if |
|---|---|---|
| Something people actually use (an internal tool, a library with users, a client site) | You ship and maintain | You can describe a real user, bug report or change request |
| A hard technical problem (a sync engine, a performance rewrite, a parser) | Depth | You can explain the trade-off you chose and what it cost |
| A build in the target role's stack | Fit | It's finished, and you'd defend the code in a review |
| Open-source contributions | You can read and work in other people's code | There are merged pull requests with real review discussion |
| Work from a job, under NDA | Real scale and constraints | You can describe it without proprietary detail |
| A tutorial clone (todo app, movie database, weather app) | Very little on its own | You added something the tutorial didn't, and you say what |
How many to feature
Feature three to five. Fewer than three makes it hard to see a pattern; more than five and the reviewer starts skimming, which means your best project competes with your weakest. Put anything else in a short "Other work" list with one line and a link each.
What to cut
- Tutorial projects you didn't extend.
- Repos with no README, or a README that's still the framework's default.
- Hackathon projects whose demo is broken.
- Group projects where you can't say precisely which parts were yours.
- Anything you'd be uncomfortable walking through line by line.
Cutting is hard because each project cost you weekends, but reviewers don't grade on effort. Four good projects read stronger than four good ones plus three weak ones.
Match the portfolio to the role
The same engineer can show different projects for different applications. Lead with what the role screens for.
- Frontend roles care about interaction details, accessibility and performance. Show a component or app where keyboard navigation, focus states and screen reader labels work, and say how you tested them. The W3C's Web Accessibility Initiative has the standards and testing guidance to reference. There's more on presenting this kind of work on the frontend developer portfolio page.
- Backend roles care about data modeling, APIs, reliability and operations. A diagram of the system, the API's error handling, how you handled retries or idempotency, and the tests you actually wrote say more than any screenshot.
- Full-stack roles want to see one product built end to end: schema, API, UI, deployment, and the unglamorous parts like auth and migrations. One finished product beats three half-finished ones. The full-stack developer portfolio page shows one way to frame it.
Seniority changes the emphasis too. A junior engineer proves completeness and learning speed. A senior engineer should show decisions with consequences: a migration planned and run, a system redesigned, a team's tooling improved, other engineers unblocked. If you're senior and your portfolio is all side projects, add one write-up about work from your job, described at a level your employer would accept.
How to write up a project
Every featured project gets its own page. Use the same structure each time so reviewers learn where to look.
- One-line summary. What it is and who it's for. "A billing reconciliation service that matches payment processor exports against invoices for a small accounting team."
- The problem. Two or three sentences on why it needed to exist.
- Your role. Solo, or which parts you owned on a team. Be precise; overclaiming falls apart in the interview.
- Stack, with reasons. Not just a row of logos. One sentence on why each major choice fit.
- Key decisions. Two or three, each with the alternative you considered and why you rejected it. This is the section that gets you interviews.
- Results. What happened: users, uptime, a speed-up, a process that got shorter. Use numbers only if you measured them; otherwise describe the outcome plainly.
- What you'd do differently. One short paragraph. It shows judgment, and reviewers often ask anyway.
- Links. Repo, live demo, any related writing.
Here's what a decision paragraph might look like:
I used Postgres with
SELECT ... FOR UPDATE SKIP LOCKEDas the job queue instead of adding Redis. The team already ran Postgres, the volume was a few thousand jobs a day, and one fewer service meant one fewer thing to monitor. If volume grew by an order of magnitude, I'd revisit it.
That paragraph shows you know the trade-off exists, you sized the problem, and you know when the answer would change. Aim for 300 to 800 words per write-up, with a screenshot, a short recording or an architecture diagram. Include a code snippet only when the snippet is the interesting part.
GitHub links, live demos and READMEs
Link the repo, not just your profile
Link each project directly to its repository, and pin your featured repos on your GitHub profile so the two tell the same story. A profile link on its own sends the reviewer hunting.
Write the README for a stranger
A good README covers what the project is, a screenshot or GIF, how to run it locally (ideally one command), a short architecture note, and how to run the tests. Before you share a repo, check its commit history for leaked API keys or credentials. Deleting a key in a later commit doesn't remove it from history, so rotate it.
Keep demos alive, or don't link them
A dead demo link is worse than no demo. Some free hosting tiers put idle apps to sleep or remove old databases, so a demo that worked when you applied may fail when the reviewer clicks. Check your links before each round of applications, and keep a short recording as a fallback.
If the app needs an account, don't make the reviewer sign up. Provide a demo login with read-only sample data, or a "try it" mode that skips sign-in.
The resume page and site structure
Keep the site small. A software engineer portfolio usually needs:
- Home: a one-line positioning statement ("Backend engineer who builds billing and payments systems") and your featured projects as cards.
- Project pages: one per featured project, using the write-up structure above.
- Resume: the same facts as your PDF resume and LinkedIn, as an HTML page with a PDF download. Dates, titles and links to the matching projects.
- About: short. What you work on, what you're looking for, and where you're based.
- Contact: an email link plus GitHub and LinkedIn. A form isn't necessary.
The site is also a code sample, whether you mean it to be or not. It should load fast, use real headings, work on a phone and pass a basic accessibility check. If you're a generalist rather than a specialist, the developer portfolio page has a starting structure along these lines.
Should you hand-build the site to prove skill? For a frontend role where the portfolio is itself the showcase, maybe. For everyone else, the projects are the proof, and hours spent on portfolio CSS are hours not spent finishing the project that would have impressed someone.
Getting the site built
If you'd rather put your evenings into the projects, you can build a software engineer portfolio with FNJ's AI builder: it starts from a prompt written for engineers plus a screenshot or link of a site whose look you like, designs every page at desktop, tablet and phone widths, and exports a Next.js App Router project or static HTML, or pushes to a branch of your own GitHub repository. Every builder plan includes an MCP server, so Cursor or Codex can edit the site later on the AI subscription you already pay for, without using credits. It's a paid tool, it doesn't build contact forms (an email link is fine here), and the project write-ups still have to come from you, because nobody else knows why you chose Postgres.
Frequently asked questions
How many projects should a software engineer portfolio have?
Feature three to five projects, each with its own write-up, and list anything else in a short "other work" section. Fewer than three makes it hard to see a pattern, and more than five dilutes your best work.
Should I include projects from my current or past job?
Yes, if you can describe them without proprietary details: the problem, your role, the decisions and the outcome, with your own diagrams instead of internal ones. Don't share company code, and check your employment agreement if you're unsure what you can disclose.
Do I need a live demo for every project?
No. Anything with a user interface benefits from a demo, but backend projects can be shown with an architecture diagram, API documentation, test output or a short screen recording. A broken demo link hurts more than a missing one, so check them before each application.
Is a GitHub profile enough instead of a portfolio site?
GitHub shows your code but not why you made the choices you did, and a reviewer short on time may never open a repository unprompted. A portfolio site puts the projects that matter up front, frames each with a write-up, and links to the code for anyone who wants more.