Learn Astro Framework Guide — Build Faster Websites with Island Architecture

Astro Framework Guide — Build Faster Websites with Island Architecture

DodaTech Updated Jun 7, 2026 6 min read

Astro is a modern web framework that ships zero JavaScript by default and uses island architecture — meaning your page loads fast because only interactive components send JavaScript to the browser, while static content is pure HTML.

What You’ll Learn

How Astro’s island architecture works and why it makes sites faster
Writing .astro components and combining them with framework components
Using content collections to manage Markdown and MDX content
Integrating React, Vue, and Svelte components in the same project
Building and deploying an Astro site

Why Astro Matters

Most web frameworks send JavaScript for every page element — even the static ones. Astro flips this: it sends zero JS by default and only hydrates interactive “islands” on demand. This means your site loads fast on slow connections, scores higher on Core Web Vitals, and gives users a better experience. Doda Browser uses Astro for its documentation site because performance matters when developers are looking up APIs on slow network connections.

    flowchart LR
    A[HTML & JavaScript Basics] --> B[Astro]
    B --> C[Island Architecture]
    B --> D[Content Collections]
    B --> E[Framework Integrations]
    C --> F[Fast Static Sites]
    D --> G[Blog / Docs]
    E --> H[Interactive Islands]
    style B fill:#ff5a03,color:#fff

Prerequisites: Familiarity with HTML, JavaScript, and at least one UI framework like React or Vue. No prior Astro experience needed.

Core Concepts

Island Architecture

The heart of Astro is islands — interactive components floating in a sea of static HTML. Instead of hydrating the entire page, Astro hydrates only the parts that need JavaScript:

---
// This .astro component renders 100% static HTML
// No JavaScript sent to the browser
---
<header>
  <nav>
    <a href="/">Home</a>
    <a href="/about">About</a>
  </nav>
</header>

<!-- This React component becomes an interactive island -->
<HeaderSearch client:load />

Output: The <header> is plain HTML. The <HeaderSearch> component loads its JavaScript only when the page loads in the browser. Everything else stays lightweight.

.astro Component Syntax

Astro components use a --- frontmatter section for server-side logic and HTML for the template:

---
// This runs on the server at build time
const pageTitle = "Welcome to Astro";
const posts = await Astro.glob("./posts/*.md");
---
<!DOCTYPE html>
<html>
<head>
  <title>{pageTitle}</title>
</head>
<body>
  <h1>{pageTitle}</h1>
  <ul>
    {posts.map(post => (
      <li><a href={post.url}>{post.frontmatter.title}</a></li>
    ))}
  </ul>
</body>
</html>

Output: An HTML page with a list of blog post links. Zero JavaScript is sent to the browser — just clean HTML.

Content Collections

Astro’s content collections provide type-safe Markdown and MDX management:

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

const blogCollection = defineCollection({
  schema: z.object({
    title: z.string(),
    date: z.date(),
    tags: z.array(z.string()).optional(),
    draft: z.boolean().default(false),
  }),
});

export const collections = {
  blog: blogCollection,
};

// src/pages/blog/[...slug].astro
---
import { getCollection } from "astro:content";

export async function getStaticPaths() {
  const posts = await getCollection("blog");
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}
---
<article>
  <h1>{post.data.title}</h1>
  <Content />
</article>

Output: Astro generates a static HTML page for each blog post at build time, with frontmatter validated against your schema. No runtime database queries needed.

Framework Integrations

You can mix components from different frameworks in the same Astro project:

---
import ReactCard from "../components/ReactCard.tsx";
import VueCounter from "../components/VueCounter.vue";
import SvelteButton from "../components/SvelteButton.svelte";
---

<ReactCard title="React Island" client:visible />
<VueCounter client:idle />
<SvelteButton client:media="(min-width: 768px)" />

Output: Each component becomes an island with its own hydration strategy. client:visible loads when the card scrolls into view. client:idle loads after the page is idle. client:media loads only on desktop screens.

Deployment

Astro builds to static files by default — deploy anywhere:

# Build the site
npm run build

# Output in dist/ — deploy to Netlify, Vercel, Cloudflare, or any static host

# For SSR (server-side rendering)
# Add adapter: npx astro add netlify
# Then: npm run build  # outputs server-side handler

Common Mistakes

Forgetting the client:* directive on interactive components: Without client:load, client:idle, or client:visible, interactive framework components render as static HTML with no JavaScript. They won’t work.
Using Astro for highly dynamic apps: Astro excels at content-heavy sites. If every page element needs interactivity, a framework like Next.js or Remix may be a better fit.
Not validating content collection schemas: Without a Zod schema, you lose type safety and validation. A typo in frontmatter goes unnoticed until runtime.
Mixing too many frameworks in one project: While Astro supports React, Vue, Svelte, and more, each framework adds bundle size. Stick to one or two for production sites.
Assuming all files in src/pages/ become routes: Astro only treats .astro and .md files as pages. Components in src/components/ are not routable.

Practice Questions

What is island architecture and how does it improve performance? Answer: Island architecture means only interactive components send JavaScript to the browser. Static content stays as pure HTML, reducing bundle size and improving load times.
How do you make a React component interactive in an Astro page? Answer: Add a client:* directive like client:load or client:visible to the component tag. Without it, the component renders as static HTML.
What is the purpose of content collections? Answer: Content collections provide type-safe, validated management of Markdown and MDX content with automatic schema checking via Zod.
Why would you choose Astro over Next.js? Answer: Choose Astro for content-heavy sites (blogs, docs, marketing pages) where most content is static. Choose Next.js when you need extensive server-side rendering or API routes.

Challenge

Build a portfolio site with Astro: create a content collection for projects (title, description, tags, image), display them in a grid, add a React-powered contact form as an island, and deploy to Netlify.

FAQ

Does Astro support SSR?

: Yes. Add an adapter (Netlify, Vercel, Cloudflare, Node) to enable server-side rendering instead of static generation.

Can I use Astro with a CMS?

: Absolutely. Astro integrates with WordPress, Strapi, Contentful, and headless CMS platforms via its data-fetching capabilities.

Is Astro production-ready?

: Yes. Astro 4.x is stable and used in production by companies like Google, Firebase, and The Guardian.

How does Astro compare to Hugo or 11ty?

: Astro is closer to 11ty — both support multiple template languages and static output. Astro adds island architecture and framework integration that Hugo doesn’t have.

What is the client:load directive?

: It tells Astro to hydrate and load the component’s JavaScript immediately when the page loads in the browser.

Try It Yourself

# Create a new Astro project
npm create astro@latest my-astro-site
cd my-astro-site

# Add a framework integration
npx astro add react

# Start the dev server
npm run dev

Create an .astro component that imports a React counter, make it interactive with client:load, and observe in the browser’s network tab that only the counter’s JavaScript is loaded — not the entire page.