Back to Blog

Building a Portfolio with Astro's Island Architecture

Discover how Astro's island architecture enables you to build fast, interactive portfolio sites that ship zero JavaScript by default.

A
Astro Team
|
astro islands performance

Astro’s island architecture is a game-changer for building portfolio sites. By default, Astro renders everything to static HTML — meaning your pages load instantly with zero JavaScript. When you need interactivity, you add “islands” of dynamic components that hydrate independently.

Why Islands Matter for Portfolios

Portfolio sites have a unique challenge: they need to showcase visual content beautifully while remaining fast and accessible. Traditional single-page applications ship a large JavaScript bundle even though most of the content is static. Astro flips this model entirely.

Consider a typical portfolio page with:

  • A hero section with an animation
  • A grid of project cards
  • A contact form
  • A theme toggle

With Astro, only the theme toggle and contact form need JavaScript. The hero animation can use CSS, and the project grid is pure HTML. This means your portfolio loads in under 100ms on a fast connection.

Adding Interactive Islands

To add interactivity, you use client directives on your components:

---
import ThemeToggle from '../components/ThemeToggle.tsx';
import ContactForm from '../components/ContactForm.tsx';
---

<!-- Only these components ship JavaScript -->
<ThemeToggle client:load />
<ContactForm client:visible />

The client:load directive hydrates immediately, while client:visible waits until the component scrolls into view. This fine-grained control means you never ship more JavaScript than necessary.

Combining with Content Collections

For a portfolio, you can define a projects collection with rich frontmatter:

---
title: "E-Commerce Platform"
description: "A full-stack e-commerce solution"
startDate: 2025-06-01
status: "completed"
techStack: ["React", "Node.js", "PostgreSQL"]
featured: true
---

Then query featured projects on your homepage and all projects on a dedicated projects page. The type safety ensures every project has the required fields, and you can filter by status, featured status, or any other criteria.

Performance Results

In real-world testing, Astro portfolio sites consistently achieve:

  • 95+ Lighthouse performance scores
  • Less than 50KB of total JavaScript (including interactive islands)
  • First Contentful Paint under 1 second on mobile

These results are achievable because Astro’s architecture fundamentally minimizes the amount of JavaScript that reaches the browser. When you combine this with TailwindCSS’s utility-only approach, you get a site that’s both beautiful and blazingly fast.