Ship less.
Build faster.
Meet Astro.

The framework that dared to ship nothing

Every JavaScript framework of the last decade shared a quiet assumption: the browser needs to run code to build your UI. React, Vue, Angular — they all ship a runtime to the browser, execute it on load, and construct the page in JavaScript. For interactive apps, this makes sense. For a website that's mostly text, images, and links? It's like renting a bulldozer to plant a flower.

Astro was built on a different premise. Your HTML already is the UI. Generate it once at build time — or on the server when needed — and send it over the wire. No framework runtime. No hydration step. Just fast, static HTML that loads instantly.

What Astro actually does

Astro is a web framework for content-driven websites — marketing sites, blogs, documentation, portfolios. It:

Where Astro sits in the ecosystem

The web framework space is crowded. Before you can appreciate what makes Astro different, you need to know who else is in the room.

The honest take

The ideas that make Astro different

Islands Architecture

This is Astro's signature idea. In a traditional React app, the entire page is a React tree — everything hydrates, everything re-renders. In Astro, the default is static HTML. You opt specific components into interactivity using client directives.

---
import Header  from './Header.astro';  // static — zero JS
import Counter from './Counter.jsx';   // a React component
import Map     from './Map.svelte';     // a Svelte component
---
<Header />                          <!-- static HTML, 0 bytes JS -->
<Counter client:load />           <!-- hydrates immediately -->
<Map     client:visible />        <!-- hydrates when scrolled into view -->
<Chart   client:idle />           <!-- hydrates when browser is idle -->

Content Collections

If you're building a blog or docs site, content collections are a game-changer. You define a schema for your Markdown files, and Astro validates every file against it at build time. Missing a required field? Build error. Wrong type? Build error.

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

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title:       z.string(),
    publishDate: z.date(),
    author:      z.string().default('Anonymous'),
    tags:        z.array(z.string()).optional(),
    draft:       z.boolean().default(false),
  }),
});

export const collections = { blog };

Rendering Modes

View Transitions

Astro 3+ ships built-in View Transitions — smooth, SPA-like page animations with a single import. Add <ViewTransitions /> to your layout and Astro uses the browser's native View Transitions API, with a polyfill fallback. You get the feel of a single-page app without the architecture of one.

Cloudflare vs Vercel — the honest comparison

Once you've built your Astro site, you need somewhere to deploy it. The two most popular choices are Vercel and Cloudflare Pages — and the decision matters more than you'd think, especially if you're using SSR.

For static Astro (no SSR)

If your Astro site is fully static, the choice is nearly academic. Both give you:

For SSR Astro — this is where it gets interesting

When you add server-side rendering, you need an adapter. Astro ships official adapters for both:

// For Cloudflare Pages
import cloudflare from '@astrojs/cloudflare';
export default { adapter: cloudflare() };

// For Vercel
import vercel from '@astrojs/vercel/serverless';
export default { adapter: vercel() };

The verdict

What makes an .astro file tick

Every component and page in an Astro project lives in a .astro file. It looks like HTML. It mostly is HTML. But it has three superpowers that plain HTML never had: a build-time script, a component model, and automatic CSS scoping.

Anatomy of an .astro file

An .astro file has up to four distinct zones, each with a different purpose and a different runtime:

A complete annotated example

---
// Zone 1: runs at build time — never shipped to the browser
interface Props {
  title: string;
  date:  Date;
  href:  string;
}

const { title, date, href } = Astro.props;
const formatted = date.toLocaleDateString('en-US', {
  month: 'long', year: 'numeric'
});
---

<!-- Zone 2: HTML template with expressions -->
<article class="card">
  <time>{formatted}</time>
  <h2><a href={href}>{title}</a></h2>
  <slot />  <!-- renders children passed from the parent -->
</article>

<!-- Zone 3: scoped CSS — .card only applies to this component -->
<style>
  .card {
    background: #1a1a2e;
    border-radius: 8px;
    padding: 1.5rem;
  }
</style>

<!-- Zone 4: client script — this DOES ship to the browser -->
<script>
  document.querySelector('.card')
    ?.addEventListener('click', () => console.log('clicked'));
</script>

Key template syntax

{/* Expressions — any JS expression in curly braces */}
<p>{2 + 2}</p>                            <!-- renders: 4 -->
<p>{name.toUpperCase()}</p>               <!-- renders: NAME -->

{/* Conditional rendering */}
{isLoggedIn && <Dashboard />}            <!-- short-circuit -->
{isLoggedIn ? <Dashboard /> : <Login />} <!-- ternary -->

{/* Rendering lists */}
{posts.map(post => (
  <PostCard title={post.title} href={post.slug} />
))}

{/* Spread props */}
<Button {...props} />

{/* Raw HTML — use carefully, XSS risk */}
<div set:html={markdownContent} />

How .astro compares to the alternatives

Understanding what makes .astro unique requires knowing what problem each format was designed to solve — and where their boundaries lie.

.astro vs .html

The output of an .astro file is plain HTML. But the authoring experience is radically better — you get components, logic, and type safety without shipping a runtime to your users.

.astro vs .jsx / .tsx

The rule of thumb: use .astro for structure, layout, and content. Use .jsx wrapped in a client:* directive when you need interactivity or state.

.astro vs .mdx

MDX is Markdown with JSX embedded — designed for prose that occasionally needs interactive components. .astro is for the structure that wraps that prose.

The problem .astro uniquely solves

Every format before .astro forced a tradeoff:

• .html — simple, but no components or logic
• .jsx — components and logic, but ships a runtime and requires hydration
• .mdx — components in prose, but awkward for layout and structure
• Handlebars/Nunjucks — templates with logic, but not component-oriented

.astro is the first format that gives you a full component model, TypeScript, logic, scoped CSS, and zero runtime cost — because all that work happens before the HTML ever reaches a browser.

Quick Reference

Client Directives

Frontmatter Essentials

Deployment Adapters