Most portfolio sites are over-engineered. You reach for React because you know React, wire up a router, bundle 300 KB of JavaScript, and ship it to a user who just wants to read your about page. Astro was built to break that cycle.

This site — uaslim.com — is an Astro project. Zero client-side JavaScript on most pages. Sub-second loads globally. Full support for React, TypeScript, and Tailwind where needed. Here's how Astro achieves that without compromise.

The Core Philosophy: HTML-First

Astro starts from a different premise than React, Next.js, or SvelteKit. Those frameworks assume you're building an application — state, routing, hydration, the whole runtime. Astro assumes you're building a document. HTML is the primary output; JavaScript is optional.

An Astro component looks familiar:

---
// Component script — runs at build time (server-side), never in browser
const posts = await getCollection('blog');
const sorted = posts.sort((a, b) =>
  new Date(b.data.date).getTime() - new Date(a.data.date).getTime()
);
---

<!-- Template — compiled to pure HTML -->
<ul>
  {sorted.map(post => (
    <li>
      <a href={`/blog/${post.id}/`}>{post.data.title}</a>
      <time>{post.data.date}</time>
    </li>
  ))}
</ul>

The frontmatter (between ---) runs at build time. The template compiles to static HTML. The browser receives markup, not a JavaScript bundle that generates markup. For a blog post list, that's the correct model.

Islands Architecture

Islands Architecture is Astro's answer to the question: what if I need interactivity in one part of the page?

The metaphor: a static HTML page is an ocean. Interactive components are islands. Each island is an independent, self-contained piece of UI that hydrates independently — without hydrating the entire page.

---
import StaticHeader from './StaticHeader.astro';   // 0 JS
import BlogList from './BlogList.astro';            // 0 JS
import SearchWidget from './SearchWidget.tsx';      // React — hydrated!
import Footer from './Footer.astro';               // 0 JS
---

<StaticHeader />
<BlogList posts={posts} />

<!-- client:load → hydrate immediately when page loads -->
<SearchWidget client:load />

<Footer />

The client: directive is how you opt a component into client-side JavaScript. Without it, even a React component renders to static HTML at build time and ships no runtime JavaScript.

The Five Hydration Directives

The defaults are deliberately conservative. client:idle and client:visible are the most useful — they defer JavaScript parsing until the browser has nothing better to do, or until the user actually scrolls to the component.

<!-- Chat widget — loads only when user scrolls to it -->
<AiChatWidget client:visible />

<!-- Cookie banner — only on mobile -->
<MobileCookieBanner client:media="(max-width: 768px)" />

<!-- Analytics dashboard — needs browser APIs, never SSR -->
<AnalyticsDashboard client:only="react" />

This granularity is what makes Islands Architecture powerful. You're not choosing between "fully static" and "fully hydrated" — you're choosing per component.

Framework Agnosticism

Astro doesn't pick a frontend framework for you. It supports React, Vue, Svelte, Solid, Preact, and Lit in the same project. You import the integration, and the client: directives work the same way.

npx astro add react      # @astrojs/react
npx astro add vue        # @astrojs/vue
npx astro add svelte     # @astrojs/svelte

In practice this means: use React for the interactive search widget you already have. Use Svelte for the lightweight toggle that doesn't need a full React runtime. Use plain .astro components for everything static. The bundles are separate — React's 45 KB runtime only loads on pages that need it.

---
import ReactSearchWidget from './SearchWidget.tsx';  // loads React runtime
import SvelteCounter from './Counter.svelte';         // loads Svelte runtime (~2 KB)
---

<ReactSearchWidget client:load />
<SvelteCounter client:idle />

Content Collections: Typed Markdown at Scale

Content Collections are Astro's built-in system for managing structured content like blog posts. Instead of reading Markdown files manually, you define a schema with Zod and get full TypeScript validation:

// src/content.config.ts
import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    date: z.string(),
    description: z.string(),
    tags: z.array(z.string()).optional(),
    readingTime: z.number().optional(),
  }),
});

export const collections = { blog };

Now every Markdown file in src/content/blog/ is validated against that schema at build time. Missing a required field? Build fails. Typo in a tag? TypeScript catches it. The data you get from getCollection('blog') is fully typed:

---
import { getCollection } from 'astro:content';

// posts: CollectionEntry<'blog'>[] — fully typed
const posts = await getCollection('blog');

// post.data.title — string, guaranteed
// post.data.date — string, guaranteed
// post.data.readingTime — number | undefined, correct
---

For a blog, this replaces a CMS, a database, and a content API. Your Markdown files are the source of truth, Git is version control, and TypeScript is validation.

The Build Output: What Actually Ships

Running astro build produces a dist/ folder of pure HTML, CSS, and minimal JavaScript. For a typical content site:

dist/
  index.html          — 12 KB
  blog/
    index.html        — 8 KB
    my-post/
      index.html      — 15 KB
  _astro/
    main.css          — 18 KB (Tailwind, purged)
    SearchWidget.js   — 48 KB (React runtime + component, only on pages that use it)

Compare that to a Next.js app with the same content: 200+ KB of JavaScript on the initial page load, even for pages with no interactivity.

The Lighthouse scores reflect this. A static Astro page with no interactive islands routinely scores 98-100 on performance. The JavaScript budget only grows when you explicitly spend it.

View Transitions: SPA Feel, Static Output

Astro's View Transitions API gives you smooth page-to-page animations without a client-side router. One import, one attribute:

---
// layouts/Layout.astro
import { ViewTransitions } from 'astro:transitions';
---

<html>
  <head>
    <ViewTransitions />
  </head>
  <body>
    <slot />
  </body>
</html>

Under the hood this uses the browser's native View Transitions API with a polyfill for unsupported browsers. Navigation feels like an SPA — no full page flash, animated transitions — but the HTML is still served statically per page. No client-side routing JavaScript, no prefetch bundle bloat.

You can annotate specific elements for custom transitions:

<!-- Blog card that "expands" into the article on click -->
<img
  src={post.data.coverImage}
  transition:name={`cover-${post.id}`}
  transition:animate="slide"
/>

Astro matches the transition:name between the list and the detail page and animates between them using the browser's native API. The effect is striking; the cost is near-zero.

When Astro Is the Right Choice

Astro is well-suited for:

• Marketing sites and landing pages — mostly content, minimal state, SEO critical
• Documentation sites — large amounts of Markdown, fast navigation, search as an island
• Portfolios and blogs — exactly what this site is
• E-commerce product pages — static product listing, React cart widget as an island
• Hybrid apps — static shell with interactive sections

Astro is a poor fit for:

• Highly interactive single-page applications — a dashboard with complex state, real-time updates, frequent client-side navigation. React + Vite or Next.js App Router serves you better.
• Apps where every route is behind auth — Astro can do SSR, but if every page is personalized and dynamic, the static-first model loses its advantage.
• Real-time features — live data, WebSockets, collaborative editing. These need a proper SPA runtime.

The honest test: count the interactive components on your page. If it's one or two (a search bar, a contact form, a theme toggle), Astro is probably the right choice. If every component manages state and communicates with siblings, you want a full SPA framework.

SSR Mode: Opting Into Dynamic Rendering

Astro isn't locked to static output. Setting output: 'server' in astro.config.mjs switches to server-side rendering on every request, just like Next.js:

// astro.config.mjs
export default defineConfig({
  output: 'server',
  adapter: vercel(),   // or node(), cloudflare(), etc.
});

Or you can use output: 'hybrid' — static by default, with opt-in dynamic routes:

---
// pages/api/contact.ts — dynamic API endpoint
export const prerender = false;

export async function POST({ request }) {
  const data = await request.json();
  await sendEmail(data);
  return new Response(JSON.stringify({ ok: true }), { status: 200 });
}
---

---
// pages/blog/[slug].astro — stays static
// (prerender defaults to true in hybrid mode)
---

This hybrid model is genuinely powerful: static pages for content (fast, cacheable, CDN-friendly), dynamic endpoints for forms and APIs. No separate backend needed for simple interactions.

Content Security Without a Build Step

One thing Astro gets right by design: there's no client-side HTML injection surface by default. .astro component templates use JSX-like syntax, and values are escaped automatically:

---
const userInput = '<script>alert("xss")</script>';
---

<!-- Renders as escaped text — safe -->
<p>{userInput}</p>

<!-- Explicit opt-in required for raw HTML -->
<p set:html={sanitizedHtml} />

The set:html directive is the only way to inject raw markup, and its name is a visible signal in code review. In a CMS-driven site, this matters: you know exactly where unescaped content can flow.

The Developer Experience

A few things that make Astro pleasant to work with day-to-day:

Hot module replacement is instant. Astro's dev server only re-processes the changed component, not the whole page. On large sites this is noticeable.

TypeScript is on by default. No config required. .astro files support TypeScript in the frontmatter, and getCollection() returns typed data automatically.

Zero-config image optimization. The <Image /> component from astro:assets generates WebP/AVIF variants, adds correct width and height attributes (preventing layout shift), and lazy-loads by default. One line replaces a webpack image pipeline.

---
import { Image } from 'astro:assets';
import heroImage from '../images/hero.jpg';
---

<!-- Optimized, correctly sized, lazy-loaded, WebP format -->
<Image src={heroImage} alt="Hero" width={1200} height={630} />

Production Checklist

Before shipping an Astro site:

# Run a full build — catches type errors and missing content
npm run build

# Preview the static output locally — catches routing issues
npm run preview

# Check bundle size per page
npx astro build --verbose

# Validate HTML output
npx html-validate dist/**/*.html

The most common production issue: client:only components that reference window or document during SSR. Astro warns on these — fix them before the build, not after.

This site uses Astro 5 with the hybrid output mode — static pages for everything, a small server function for the contact form. The result is a Lighthouse performance score of 98 and a first contentful paint under 400ms globally, with zero JavaScript shipped to blog post pages. That's the Islands Architecture working exactly as designed.

Have questions about Astro's architecture or thinking about migrating a site? Drop me a line.