I applied for a role at a mid-sized SaaS company about two years into my career. Strong company, interesting problem, good pay. I sent my application, got a recruiter callback, and then nothing for two weeks. When the feedback finally came: "We went with candidates with a stronger portfolio presence."
I had 23 GitHub repositories. I had a portfolio site. I had projects. What I didn't have — and what I didn't understand for another six months — was a portfolio that told a story. I had code. Not evidence of thinking, decision-making, or the ability to ship something real.
I've since built, rebuilt, and advised on a lot of developer portfolios. I've seen what gets people calls and what gets them ghosted. This isn't a guide about which framework to use or how to pick colors. It's about what actually moves the needle — the things I wish someone had told me in year one.
Lesson 1: Two Great Projects Beat Twenty Mediocre Ones
The instinct is to fill the portfolio. More projects = more evidence of experience. This is wrong.
A hiring manager or engineering lead looking at your portfolio has about three minutes. They're going to look at your two or three most prominent projects, click one or two live demo links, and form an opinion. If they see twenty repositories and most of them are "Todo App v2," "Weather App," "Netflix Clone," "Portfolio v1 through v6" — they've already categorized you as someone who builds tutorials, not someone who builds things.
The better approach: three to five projects, each with:
- A real problem it solves (not "I wanted to learn React")
- A live deployment that actually works
- A README that explains why you made the decisions you made
- Enough complexity to have generated at least one interesting engineering problem
Projects that tend to work: tools you built because you were frustrated with an existing tool, apps solving problems you personally had, projects where you integrated with a real API or real data source, anything with a live user base (even 10 users counts).
Projects that tend not to work: tutorial clones (unless heavily modified), apps that only run locally, projects that stop at the MVP and never got deployed, apps with the same name as thousands of other developer portfolios ("My Todo App," "My Weather App").
If you have 20 repos, that's fine. Pin your three best to your GitHub profile. Don't make people wade through everything — curate it.
Lesson 2: Case Studies Beat Code Screenshots
Here's the thing about showing a screenshot of your app: everyone can make an app look good in a screenshot. Filters, cropping, ideal state data. A screenshot shows what you built. It tells me nothing about how you think.
A case study shows how you think. And how you think is what you're being hired for.
A case study doesn't have to be a five-page document. Two or three paragraphs on each project covering:
- The problem. What did you set out to solve? Be specific. Not "I wanted to learn Next.js" — that's not a problem. "Resume submissions were getting lost in email threads, so I built a tool that…" — that's a problem.
- Your approach and the tradeoffs you considered. What did you think about? What did you try first? What didn't work? This is where you demonstrate that you can make technical decisions, not just execute instructions.
- What you shipped. Not every feature you imagined — what you actually built and deployed.
- What you'd do differently. This one is disarming in the best way. It shows self-awareness, reflection, and the ability to evaluate your own work critically. Engineers who can't critique their own code can't grow.
I've seen portfolios with two projects and a well-written case study for each that outperformed portfolios with fifteen projects and no context. The case study gives an interviewer something to ask about. It shows you've thought deeply about the work. It makes the technical interview easier because you already answered half the questions in writing.
Lesson 3: If It's Not Deployed, It Doesn't Exist
This is the blunt version. A project that runs on localhost is a project you're still working on. It is not a portfolio piece.
I've reviewed portfolios where the "live demo" link was a localhost URL. I've seen GitHub repositories where the README says "deployment in progress" with a date from 18 months ago. I've seen apps in screenshots that couldn't actually run because they depended on a local database with no seed data.
Deploying has never been easier or cheaper. There's no excuse for a portfolio project that isn't live.
- Frontend: Vercel (free), Netlify (free), Cloudflare Pages (free). Zero configuration for most frameworks.
- Backend / API: Railway (free tier), Render (free tier), Fly.io (free tier). These all support Node.js, Python, Go, whatever you're running.
- Database: MongoDB Atlas free tier (512MB), Supabase free tier (PostgreSQL), PlanetScale free tier (MySQL).
- Full stack: Railway handles full-stack apps well. Render lets you deploy multiple services from one repo. Both have one-click GitHub deploys.
Total cost of a deployed side project: $0, with a free domain subdomain. Add a custom domain for $12/year and you have a genuinely professional-looking production deployment.
There's a secondary benefit to deploying: it forces you to actually finish things. There's a long list of problems you don't know about until you deploy — environment variable management, CORS configuration, database connection pooling, static asset serving. Deploying is part of building. A portfolio project that's never been deployed has never been truly finished.
Lesson 4: The README Is Your First Interview
When a hiring manager or senior engineer clicks the GitHub link from your portfolio, the first thing they see is the README. If it says "A project I made for learning" or has no description at all, they've already lost interest.
The README is where you make the technical case for yourself before you're in the room. Here's what a good one contains:
First paragraph: What does this thing do and why does it exist? Not "this is a web app" — tell me the specific problem it solves. One or two sentences.
Tech stack and why: Not just a logo grid. A sentence about why you chose what you chose. "Used PostgreSQL instead of MongoDB because the data has strong relational structure with lots of joins." "Chose Next.js App Router over CRA because we needed SSR for SEO and a built-in API layer." These sentences prove you made intentional decisions.
Screenshots or a GIF: A 10-second screen recording of the app working is worth a thousand words. Not staged, not filtered — just the actual app.
How to run it: Clear, complete instructions. If I clone it and follow your README and it doesn't work, that's a flag. If it works first try, that's a positive signal — it means you document carefully and you care about the developer experience of your code.
Known limitations / what you'd do differently: One paragraph. Shows maturity. "If I built this again, I'd use a message queue for the email sending instead of doing it synchronously in the request lifecycle — it caused timeouts under load."
This README takes maybe 45 minutes to write. It dramatically changes how your project is perceived.
Lesson 5: Get Your Own Domain
This one is simple and often skipped. Your portfolio should live at yourname.com or yourname.dev — not github.io/yourname/portfolio or yourname.netlify.app.
A custom domain does two things: it signals that you take yourself seriously as a professional, and it's a much better URL to put on a resume, LinkedIn, or business card. "theharshdeepsingh.com" looks intentional. "harshdeep-singh-13.github.io/portfolio-2024" looks like a homework assignment.
Domains cost $10–15 per year. That is a rounding error in any budget. Buy yours today. Redirect your GitHub Pages / Vercel / Netlify deployment to it. It takes 30 minutes and it never needs to change — you own it.
A note on choosing the domain: use your name. Not your "developer brand" or a clever handle. Names rank in Google. If someone searches for you, they should find your portfolio at the top. A personal domain with your name is one of the easiest SEO wins available to you.
Lesson 6: One AI Integration Changes Everything
Here's the hiring landscape in 2025 from a practical perspective: companies want developers who can work with AI, build on top of AI APIs, and integrate AI capabilities into existing products. This is new enough that not everyone has done it. Old enough that "I'm planning to learn it" isn't a compelling answer.
One project with a real AI integration moves you from the pile to the shortlist. Not because AI is a magic word — but because it demonstrates technical currency. You know what the OpenAI API looks like. You've dealt with token limits and streaming and prompt engineering. You've thought about cost and abuse prevention. These are all non-trivial.
What counts:
- A feature in an existing project that uses GPT-4o, Claude, or Gemini for a specific, meaningful task (not "ask AI anything" — that's too vague to be impressive)
- A RAG (retrieval-augmented generation) pipeline — document upload, embedding, search, answer generation
- An agent that takes structured actions based on LLM output (web search, database queries, API calls)
- A classification or extraction feature that uses an LLM where a simpler approach wouldn't have worked
What doesn't count:
- "Used ChatGPT to help me write this code" (everyone does this)
- A UI wrapper around ChatGPT that just passes prompts through (no engineering decision was made)
- A project that uses AI for something that a regex would handle just as well
The bar isn't high. Ship one genuinely useful AI feature, document the decisions you made (model selection, prompt design, cost management), and you're ahead of the majority of developers applying for the same roles.
Watch: Portfolio Reviews — What Actually Works
Weak vs. Strong Portfolio Signals
Signal
Weak
Strong
Project count
20+ repos, half are tutorial clones
3–5 curated projects, each with a clear purpose
Project quality
Todo apps, weather apps, Netflix/Airbnb clones
Tools solving real problems, deployed with real users
Live demos
No live link, "works on my machine," localhost screenshots
Deployed URLs that load in under 3 seconds
Documentation
No README or "this is a project I made"
Problem statement, tech choices explained, known limitations
Tech recency
Create React App, class components, outdated dependencies
Current stack (Next.js 15, TypeScript, modern APIs)
AI integration
None, or "used AI to help me code"
One genuine AI feature with documented engineering decisions
Domain
github.io/username or platform subdomain
yourname.com — personal, memorable, professional
Case studies
Screenshots in a grid with a "View Project" button
Problem → approach → tradeoffs → outcome — per project
What I'd Do on Day 1 If I Were Starting Over
If I were a developer today with no portfolio and a job to find, here's the exact sequence I'd follow:
Day 1: Register firstnamelastname.com. It costs $12. Do it before you build anything. Having the domain makes the whole thing feel real and gives you a deadline.
Week 1: Identify one problem I genuinely have — something I do manually that should be automated, something I've searched for that doesn't exist, something at work that annoys me. Build the simplest version of the solution. Not a full product — a working tool. One feature, deployed.
Week 2: Write the case study. What was the problem? What did I consider? What did I ship? What didn't make the cut? What would I do differently? Two or three paragraphs per question. This is more valuable than the code itself.
Week 3: Add an AI integration to the project — something that actually makes the tool better, not a bolt-on. Even a single endpoint that uses an LLM for classification or text generation counts, as long as it's doing something a simpler approach couldn't.
Week 4: Point the domain at the project. Add the URL to LinkedIn's "Featured" section and your resume. Ask one person who is not a developer to try using the tool and tell you what they're confused by. Fix those things.
That's it. One good project, one good case study, one AI integration, a custom domain, a LinkedIn presence. Four weeks. That's a portfolio that gets callbacks. Everything else is refinement.
TL;DR
- Curate, don't accumulate. Three deployed projects with case studies beat twenty unfinished repos. Pin your best work. Hide the rest.
- Write case studies for every project. Problem → approach → tradeoffs → outcome → what you'd do differently. This is what interviews are about anyway — you're just answering in advance.
- Nothing without a live URL. Free tiers on Vercel, Railway, and Render make deployment trivial. An undeployed project is an unfinished project.
- The README is your first impression from GitHub. Spend 45 minutes on it. Explain the why, not just the what. Include how to run it. List the limitations. That's a professional developer.
- Get the domain. yourname.com, $12, 30 minutes. It signals intent and makes your portfolio findable in Google searches by your own name.
- Build one thing with a real AI integration. Not a ChatGPT wrapper — a feature that uses an LLM to solve a specific problem in your project, with documented decisions about model selection and prompt design.
Top comments (0)