Getting Started with Astro: A Modern Content-First Web Framework

Table of Contents

1399 words

7 minutes

Getting Started with Astro: A Modern Content-First Web Framework

2026-06-17

Frontend

Astro

/

SSG

/

Frontend Frameworks

/

Frontend Fundamentals

1. Introduction#

Astro is a web framework designed specifically for content-driven websites. Its core philosophy is simple: if most of a page’s content doesn’t need JavaScript, then JavaScript shouldn’t be sent.

While the React/Vue community races on server-side rendering, streaming, and everything else, Astro took a completely different path:

Your blog posts, documentation pages, marketing sites—99% of the content is static. Why load a full JS runtime for that 99%?

This approach made Astro an instant hit—it won first place in “Frontend Satisfaction” for two consecutive years (2023/2024), and in 2025 became one of the fastest-growing web frameworks on GitHub by stars.

(The blog you’re reading right now is built with Astro.)

2. Islands Architecture: Astro’s Killer Feature#

2.1 The Problem with Traditional SPAs#

Traditional React/Vue single-page applications:

1
The entire page = one giant JS application
2
├── Navigation bar (requires interactivity)
3
├── Article content (purely static text)
4
├── Sidebar (purely static)
5
├── Comment section (requires interactivity)
6
└── Footer (purely static)

To load this page, the browser has to download the entire application’s JS, then “hydrate” all components. Even if 80% of the content never changes, you still pay the JS cost for it.

2.2 Astro’s Answer#

1
Whole page = pure HTML (default)
2
├── Navbar          → pure HTML (zero JS)
3
├── Article content → pure HTML (zero JS)
4
├── Sidebar         → pure HTML (zero JS)
5
├── 🏝️ Comment section → React component (hydrated on demand)
6
└── 🏝️ Like button   → Vue component (hydrated on demand)

This is islands architecture: pages are static HTML by default, and only the parts that truly need interactivity load JS as “islands.” Each island loads and hydrates independently, without interfering with the others.

3. Creating Your First Astro Project#

3.1 Initialization#

1
# npm
2
npm create astro@latest my-site
3

4
# pnpm (recommended)
5
pnpm create astro@latest my-site

The initialization wizard:

1
✔ How would you like to start?                  → Empty
2
✔ Do you plan to write TypeScript?              → Yes
3
✔ How strict should TypeScript be?              → Strict
4
✔ Install dependencies?                         → Yes
5
✔ Initialize a new git repository?              → Yes

Start the dev server:

1
cd my-site
2
pnpm dev

Visit http://localhost:4321, and your first Astro site is up and running.

3.2 Project Structure#

1
my-site/
2
├── astro.config.mjs      # Astro config file
3
├── src/
4
│   ├── pages/            # Route pages (file-system routing)
5
│   │   ├── index.astro   # Home page /
6
│   │   ├── about.astro   # /about
7
│   │   └── blog/
8
│   │       └── [slug].astro  # Dynamic route /blog/xxx
9
│   ├── components/       # Reusable components
10
│   ├── content/          # Content collections (blog posts, etc.)
11
│   ├── layouts/          # Page layouts
12
│   └── styles/           # Global styles
13
├── public/               # Static assets (copied directly to build output)
14
└── package.json

4. Astro Component Syntax#

4.1 Basic Structure#

A .astro file consists of two parts: the component script (runs on the server) and the template (outputs HTML).

1
---
2
// Component script (fence): runs on the server/at build time
3
// Can import other components, call APIs, query databases
4
const name = "Astro";
5
const items = ["SSG", "Island Architecture", "Multi-framework"];
6
---
7

8
<!-- Template section: output HTML directly -->
9
<h1>Hello, {name}!</h1>    <!-- Inline JS expressions inside { } -->
10

11
<ul>
12
    {items.map(item => <li>{item}</li>)}
13
</ul>

Key difference: the code between --- runs on the server (at build time) and is not sent to the browser. The template portion outputs pure HTML.

4.2 Props and Slots#

1
---
2
export interface Props {
3
    title: string;
4
    subtitle?: string;
5
}
6

7
const { title, subtitle } = Astro.props;
8
---
9

10
<div class="card">
11
    <h2>{title}</h2>
12
    {subtitle && <p class="subtitle">{subtitle}</p>}
13
    <!-- Slots: parent components can insert content -->
14
    <slot />
15
</div>
16

17
<style>
18
    /* Component-level styles, scoped by default */
19
    .card {
20
        padding: 1.5rem;
21
        border-radius: 12px;
22
        background: #fff;
23
        box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
24
    }
25
    .subtitle {
26
        color: #666;
27
        font-size: 0.9rem;
28
    }
29
</style>

Using this component:

1
---
2
import Card from '../components/Card.astro';
3
---
4

5
<Card title="Getting Started with Astro" subtitle="From Scratch">
6
    <p>This is some content inserted into the slot.</p>
7
</Card>

4.3 Styles Are Scoped by Default#

Astro’s <style> tag is scoped by default—styles only apply to the current component and don’t leak into other parts of the page. This is a built-in capability; you don’t need CSS Modules or styled-components.

1
<!-- This h1 style only affects this component -->
2
<style>
3
    h1 { color: red; }
4
</style>
5

6
<!-- If you need global styles -->
7
<style is:global>
8
    :root {
9
        --primary: #3b82f6;
10
    }
11
</style>

5. Content Collections#

For content-centric sites like blogs and documentation sites, Astro provides content collections—a type-safe content management system.

5.1 Defining a Collection#

1
import { defineCollection, z } from 'astro:content';
2

3
const blogCollection = defineCollection({
4
    type: 'content', // 'content' means Markdown/MDX
5
    schema: z.object({
6
        title: z.string(),
7
        published: z.date(),
8
        description: z.string().optional(),
9
        tags: z.array(z.string()).default([]),
10
        draft: z.boolean().default(false),
11
    }),
12
});
13

14
export const collections = {
15
    blog: blogCollection,
16
};

5.2 Writing Content#

1
---
2
title: Hello World
3
published: 2026-06-17
4
tags: [Astro, Blog]
5
---
6

7
This is my first Astro blog post.

5.3 Querying and Rendering#

1
---
2
import { getCollection } from 'astro:content';
3

4
const posts = await getCollection('blog', ({ data }) => {
5
    return import.meta.env.PROD ? !data.draft : true;
6
});
7

8
// Sort by date
9
posts.sort((a, b) => b.data.published.valueOf() - a.data.published.valueOf());
10
---
11

12
<h1>Blog</h1>
13
<ul>
14
    {posts.map(post => (
15
        <li>
16
            <a href={`/blog/${post.slug}`}>{post.data.title}</a>
17
            <time>{post.data.published.toLocaleDateString()}</time>
18
        </li>
19
    ))}
20
</ul>

6. Mixing Other Frameworks#

Astro’s most magical feature: you can use React, Vue, and Svelte components on the same page.

6.1 Adding Integrations#

1
# Add React support
2
pnpm astro add react
3

4
# Add Vue support
5
pnpm astro add vue
6

7
# Add Svelte support
8
pnpm astro add svelte

6.2 Using Framework Components in Astro#

1
---
2
import ReactCounter from '../components/ReactCounter.jsx';
3
import VueTodoList from '../components/VueTodoList.vue';
4
import SvelteChart from '../components/SvelteChart.svelte';
5
---
6

7
<!-- Static content, Astro renders it directly to HTML -->
8
<h1>Multi-framework Demo</h1>
9
<p>The components below come from different frameworks:</p>
10

11
<!-- React component -->
12
<ReactCounter client:load />
13

14
<!-- Vue component -->
15
<VueTodoList client:visible />
16

17
<!-- Svelte component -->
18
<SvelteChart client:idle />

6.3 Client Directives: Controlling Hydration Timing#

Every framework component needs a client:* directive to determine when to load JS:

Directive	Behavior	Use Case
`client:load`	Hydrate immediately after page load	High-priority interactions (e.g., navigation menus)
`client:idle`	Hydrate when the browser is idle	Low-priority interactions
`client:visible`	Hydrate when the component enters the viewport	Interactive components lower on the page
`client:media`	Hydrate when a media query matches	Components that only load on mobile
`client:only`	Skip SSR, client-side rendering only	Components that depend on browser APIs

1
<!-- Example: loading different components at different times -->
2
<MobileMenu client:media="(max-width: 768px)" />
3
<SearchDialog client:idle />
4
<CommentSection client:visible />
5
<ThemeToggle client:load />

7. Routing and Page Modes#

7.1 SSR Mode (Default)#

Astro is SSG by default (generates pure HTML at build time). If you need SSR (dynamic rendering on each request), add this at the top of the file:

1
---
2
export const prerender = false;
3
---
4

5
<!-- This page renders dynamically on every request -->
6
<h1>Current time: {new Date().toLocaleTimeString()}</h1>

Or enable it globally in astro.config.mjs:

1
export default defineConfig({
2
    output: 'server',  // or 'hybrid' (hybrid mode)
3
});

7.2 Three Output Modes#

Mode	Description	Use Case
`static` (default)	Generates fully static HTML at build time	Blogs, documentation sites, corporate sites
`server`	Renders on the server on each request	Sites that need dynamic data
`hybrid`	Most pages static, a few pages dynamic	Static blog + login/search functionality

8. Astro vs Other Frameworks#

Dimension	Astro	Next.js	Nuxt
Core philosophy	Zero JS by default, island enhancement	React full-stack framework	Vue full-stack framework
Default rendering	SSG	SSG	SSG
JS bundle size	Extremely low (0KB by default)	Medium	Medium
Multi-framework support	✅ Native support	❌ React only	❌ Vue only
Learning curve	Gentle (HTML-like templates)	Steep (RSC, App Router)	Medium
Best scenario	Blogs, docs, marketing sites	Complex full-stack apps	Complex full-stack apps
Build speed	Extremely fast (Go + Rust engine)	Medium	Medium

9. When to Choose Astro?#

Typical signals for choosing Astro:

Scenario	Reason
Personal blog	Purely static, zero JS, perfect Lighthouse score
Technical documentation site	Content-focused, minimal interaction
Company website / marketing page	Fast first paint, high SEO requirements
E-commerce showcase page	Product display-focused, interactions via islands
Micro-frontend aggregation	Different teams use different frameworks, Astro unifies the output

Signals not to choose Astro:

Scenario	Recommended Alternative
Extremely complex frontend interactions (e.g., online Excel)	React / Vue SPA
Need client-side state management across the entire site	Next.js / Nuxt
Team is already deeply invested in a particular framework ecosystem	Choose a solution within that ecosystem

10. Summary#

Astro’s success comes from a simple observation: most websites’ “interactions” might just be a few buttons, but traditional frameworks load a heavy runtime for the entire site.

Its design philosophy can be summarized as:

Output HTML by default, inject JavaScript on demand. “Multi-framework” isn’t a gimmick—it solves a real problem: different teams and different scenarios can each use the tools they’re best at, and Astro ultimately unifies them into a static site with optimal performance.

If you want to build a blog, documentation site, marketing page, or any website where “content > interaction,” Astro may be the best choice right now. Just like this blog—every article you’re reading right now is pure HTML generated by Astro at build time, with no unnecessary JS.

1
Learning path suggestions:
2
1. Build a personal blog with Astro (3~5 days) → understand SSG and content collections
3
2. Add one or two React/Vue island components (1~2 days) → understand island architecture
4
3. Try hybrid mode and add search functionality (3~5 days) → understand dynamic routing