How to Build a Portfolio as a Solo Developer

Step-by-step guide to building a portfolio site by yourself. Tech stack, timeline, costs, and practical advice.

What You're Building

A personal portfolio site that showcases your work, projects, and skills. This is the one project every developer should build, and ironically, most developers overthink it massively. Your portfolio is your calling card. It's what potential clients, employers, or collaborators see when they Google your name. And yet I've seen developers spend months perfecting animations on their portfolio while having zero actual projects to show.

Let me tell you about my first portfolio. It was overengineered garbage. I used a full React app with a CMS, animations on every element, and a custom blog. It took me three weeks. Nobody cared about the animations. They cared about the projects section and whether my work was any good. I've since rebuilt it twice, each time simpler than the last.

Difficulty & Timeline

Aspect	Detail
Difficulty	Easy
Time to MVP	3-7 days
Ongoing Maintenance	Low
Monetization	Indirect (leads to jobs, clients, opportunities)

Recommended Tech Stack

Astro. That's it. Astro is purpose-built for content-driven static sites, and a portfolio is exactly that. It ships zero JavaScript by default, loads incredibly fast, and lets you use components from React, Svelte, or Vue if you need interactivity for specific elements. The current release is Astro 6.4.2, and the framework sits at roughly 59,700 GitHub stars with about 3 million npm downloads a week, so you are not betting on something obscure (checked on 2026-05-30).

Pin your toolchain so future-you can rebuild it. As of this writing Astro requires Node.js v22.12.0 or higher, and odd-numbered Node versions like v23 are not supported. Tailwind CSS, which I pair with it below, is on 4.x (latest 4.3.0 at the time of writing) and pulls north of 100 million npm downloads a week, so the styling layer is just as battle-tested.

If you don't want to learn a new framework, a simple Next.js site works fine too. But honestly, a portfolio doesn't need a full React runtime. The performance difference matters because Google PageSpeed scores affect your ranking, and your portfolio should rank when people search your name.

For hosting, use Vercel or Cloudflare Pages. Both have genuinely free tiers and deploy on every git push. Vercel's Hobby plan is free forever and includes 100 GB of fast data transfer and 1 million edge requests a month, which a static portfolio will never come close to using. Cloudflare Pages goes further on the free tier with unlimited bandwidth, 500 builds a month, and up to 100 custom domains per project. Don't pay for hosting a portfolio site. It's static content (pricing checked on 2026-05-30, confirm current numbers before you commit since vendor tiers move).

Step-by-Step Plan

Phase 1: Content First (Day 1-2)

Before you write any code, gather your content. This is the step everyone skips, and it's the most important one.

Write a short bio (3-4 sentences about who you are and what you do). Collect screenshots or demo links for your best 3-5 projects. Write a one-paragraph case study for each project explaining the problem, your approach, and the result.

I've seen portfolios with beautiful designs and absolutely nothing to say. The content is the product. The design is just the packaging. Get the content right and the design becomes almost secondary.

Phase 2: Build It (Day 3-5)

Scaffold your Astro project with npm create astro@latest (the official command from the Astro docs), then pick a clean template or start from scratch with Tailwind CSS. Your portfolio needs exactly these pages: a homepage with your intro and featured projects, an individual project page for each case study, and a contact section.

That's it. You don't need a blog (unless you already write). You don't need a testimonials carousel. You don't need a skills section with animated progress bars (please, for the love of everything, don't do progress bars).

Keep the design minimal and let your work speak. Use a simple color scheme, readable typography, and plenty of whitespace. If you want inspiration, look at portfolios from designers, not developers. Developers tend to over-complicate their portfolio designs while designers keep things clean.

One thing I'll strongly recommend is adding an OG image for social sharing. When someone shares your portfolio link on Twitter or LinkedIn, a well-designed preview card makes a huge difference. Use a tool like og-image or just create one in Figma.

Phase 3: Polish & Launch (Day 5-7)

Add your contact form (Formspree or just a mailto link, don't overthink this), set up your custom domain, and deploy. Formspree's free plan allows 50 submissions a month with unlimited forms, which is plenty for a portfolio that gets a handful of inquiries (their Personal tier is $15 a month for 200 submissions if you ever outgrow it, checked on 2026-05-30). Test it on mobile. I've seen portfolios where the project images are broken on phones because the developer only tested on desktop. Embarrassing for a developer portfolio.

Run a Lighthouse audit and fix anything in the red. Your portfolio should score 95+ on all metrics. It's a static site with a handful of images. There's no excuse for poor performance.

Add structured data (JSON-LD) for your Person schema. It helps Google understand that this is a personal site and can improve how you appear in search results for your name.

Monetization Strategy

Your portfolio doesn't make money directly. It makes money indirectly by getting you jobs, freelance clients, and business opportunities. Think of it as a marketing asset.

The best portfolio monetization hack is this: add a "hire me" or "available for work" badge when you're looking for opportunities, and remove it when you're not. Simple but effective. I've gotten three freelance gigs directly from my portfolio, and every single client mentioned that the project case studies convinced them to reach out.

If you want to add a revenue stream, include affiliate links to the tools you use. "Built with Vercel, styled with Tailwind, designed in Figma." Small links to your actual tools can generate passive income if your portfolio gets decent traffic. But this is a nice-to-have, not the goal.

Common Mistakes to Avoid

Spending more time on the portfolio than on actual projects. Your portfolio is a showcase. If you have nothing to showcase, the portfolio is useless. Build real things first, then show them off.

Using a template without customizing it. Hiring managers can spot a default template instantly. At minimum, change the colors, fonts, and add your actual content. A slightly customized template is fine. An untouched one screams "I don't care."

Including every project you've ever built. Curate ruthlessly. Show 3-5 of your best projects, not 15 mediocre ones. Quality over quantity, always. I removed half my projects in my last portfolio update and got better responses from clients.

Hiding your personality. Your portfolio should feel like you. If you're funny, be funny. If you're serious and technical, lean into that. The worst portfolios are the generic ones that could belong to literally any developer. Give people a reason to remember you.

Forgetting to update it. A portfolio with projects from three years ago tells people you've stopped growing. Set a quarterly reminder to update your portfolio with recent work.

Common Errors and Fixes

create astro fails or warns about your Node version. As of the current docs, Astro requires Node.js v22.12.0 or higher, and odd-numbered releases like v23 are explicitly unsupported. If the scaffold step errors out, run node -v first. If you are below v22.12.0 or on an odd-numbered version, install an even-numbered LTS release (v22 or v24) and try again.

Tailwind classes do nothing after install. Tailwind moved to a v4 architecture (latest 4.3.0 at the time of writing) where the setup differs from the v3 tutorials you may have bookmarked. In Astro the supported path is the official Tailwind Vite plugin wired through your Astro config, not the old tailwind.config.js plus @astrojs/tailwind integration flow. If your utility classes are not applying, you are almost certainly following a v3-era guide against a v4 install. Check the version Tailwind printed during install and follow the matching docs.

Lighthouse performance score sits below 95. For a static portfolio the usual culprit is unoptimized images, not your framework. Use Astro's built-in <Image /> component so assets are resized and served in modern formats, set explicit width and height to avoid layout shift, and lazy-load anything below the fold. Run the audit from an incognito window with extensions disabled, because browser extensions inflate the numbers and make a clean site look slow.

Cloudflare Pages build hits the monthly limit. The free tier allows 500 builds a month, which is generous, but a misconfigured CI loop or committing on every keystroke can chew through it. If builds start queuing, check that you are not triggering redundant deploys on non-content branches.

Person JSON-LD does not validate. When you add structured data for the Person schema, paste the exact JSON-LD into Google's Rich Results Test before you trust it. The most common mistake is the @type value, which must be Person, and a missing or malformed url property pointing at your live domain.

Is This Worth Building?

One hundred percent yes. Every developer needs a portfolio. But here's the key insight that took me years to learn: your portfolio should take days to build, not weeks. If you're spending more than a week on it, you're procrastinating on actual work by hiding behind "perfecting" your portfolio.

The best portfolio is one that exists, shows real work, and loads fast. Build it in a weekend, deploy it, and then go build something worth adding to it. You can always iterate on the design later. What you can't do is get back the weeks you spent tweaking hover animations instead of shipping real projects.

Honestly, if you're reading this and you don't have a portfolio yet, block out next Saturday and just ship one. It doesn't have to be perfect. It has to exist.