Astro

Astro

Overview

Astro is a content-first web framework built around static HTML by default, with optional islands for client-side interactivity and opt-in server features for fullstack work.

Use Astro's defaults aggressively: render as much as possible to HTML, add JavaScript only where needed, and turn on server rendering only for routes or components that truly need it.

Part 1: Astro Core

Quick Reference

Component Model

---
interface Props {
  title: string;
  description?: string;
}

const { title, description = "No description." } = Astro.props;
---

<section class="card">
  <h2>{title}</h2>
  <p>{description}</p>
  <slot />
</section>

<style>
  .card { padding: 1rem; border: 1px solid #d1d5db; border-radius: 0.75rem; }
</style>

Named slots:

<!-- Layout.astro -->
<article>
  <header><slot name="header" /></header>
  <div class="content"><slot /></div>
</article>

<!-- Usage -->
<Layout>
  <h2 slot="header">Title</h2>
  <p>Body content here.</p>
</Layout>

Routing

File-based from src/pages/. Dynamic routes need getStaticPaths() in static mode.

---
// src/pages/blog/[slug].astro
export async function getStaticPaths() {
  const posts = [
    { slug: "hello-astro", title: "Hello Astro" },
    { slug: "content-layer", title: "Content Layer" },
  ];
  return posts.map((post) => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;
---

<h1>{post.title}</h1>

Rest params with [...slug].astro:

---
export async function getStaticPaths() {
  return [
    { params: { slug: undefined }, props: { title: "Docs Home" } },
    { params: { slug: "guides" }, props: { title: "Guides" } },
    { params: { slug: "guides/install" }, props: { title: "Install Guide" } },
  ];
}
const { title } = Astro.props;
---
<h1>{title}</h1>

Islands Architecture

All components render to static HTML by default — zero JS. Use client directives to hydrate interactive pieces:

---
import ThemeToggle from "../components/ThemeToggle.svelte";
import NewsletterForm from "../components/NewsletterForm.jsx";
import CartDrawer from "../components/CartDrawer.vue";
---

<ThemeToggle client:load />
<NewsletterForm client:visible />
<CartDrawer client:idle />

Guidance:

• Default to no directive (static)
• Prefer client:visible or client:idle over client:load
• Use client:only only for browser-only libs that cannot SSR
• Each island is isolated — you can mix React, Svelte, Vue on one page

Server Islands

Defer rendering of dynamic server components with server:defer. The page shell renders immediately; the component loads afterward.

---
import UserAvatar from "../components/UserAvatar.astro";
import AvatarFallback from "../components/AvatarFallback.astro";
---

<UserAvatar server:defer>
  <AvatarFallback slot="fallback" />
</UserAvatar>

Inside the deferred component, access cookies/sessions:

---
const session = Astro.cookies.get("session");
const userName = session ? "Alex" : "Guest";
---
<p>Signed in as {userName}</p>

Use for personalized UI that shouldn't block first paint. Don't use for content that could be static.

Content Collections (v5+ Content Layer)

Define in src/content.config.ts. Collections require a loader in v5+.

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

const authors = defineCollection({
  loader: glob({ pattern: "**/*.json", base: "./src/data/authors" }),
  schema: z.object({
    name: z.string(),
    bio: z.string().optional(),
  }),
});

const blog = defineCollection({
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/content/blog" }),
  schema: z.object({
    title: z.string(),
    pubDate: z.coerce.date(),
    author: reference("authors"),
    tags: z.array(z.string()).default([]),
  }),
});

export const collections = { blog, authors };

Query and render:

---
import { getCollection, getEntry, render } from "astro:content";

// List all
const posts = await getCollection("blog");

// Single entry + render
const entry = await getEntry("blog", "hello-astro");
const { Content } = await render(entry);
---

<ul>
  {posts.map((p) => <li><a href={`/blog/${p.id}/`}>{p.data.title}</a></li>)}
</ul>

<article>
  <h1>{entry.data.title}</h1>
  <Content />
</article>

Custom loaders for APIs/CMS:

const docs = defineCollection({
  loader: myCmsLoader({ endpoint: "https://cms.example.com/docs" }),
});

Assets

---
import { Image, Picture } from "astro:assets";
import hero from "../assets/hero.jpg";
---

<Image src={hero} alt="Hero" width={1200} height={800} />
<Picture src={hero} alt="Hero" widths={[480, 960, 1440]} formats={["avif", "webp"]} />

Part 2: Astro Server / SSR / Fullstack

Quick Reference

Rendering Modes

// astro.config.mjs — mostly static site with some SSR pages
import { defineConfig } from "astro/config";
import node from "@astrojs/node";

export default defineConfig({
  output: "static",
  adapter: node(),
});

Per-page SSR opt-in:

---
export const prerender = false; // this page renders on demand

const user = Astro.cookies.get("session");
---
<h1>{user ? "Welcome back" : "Welcome"}</h1>

Note: output: "hybrid" was removed in Astro v5. Use output: "static" + prerender = false per route instead.

Actions (Type-Safe Server Functions)

Define in src/actions/index.ts:

// src/actions/index.ts
import { defineAction } from "astro:actions";
import { z } from "astro/zod";

export const server = {
  subscribe: defineAction({
    accept: "form",
    input: z.object({ email: z.string().email() }),
    handler: async ({ email }) => {
      return { message: `Subscribed ${email}` };
    },
  }),

  searchProducts: defineAction({
    input: z.object({ query: z.string().min(2) }),
    handler: async ({ query }) => {
      return [{ id: "p1", name: `Match for ${query}` }];
    },
  }),
};

Call from client:

<script>
  import { actions } from "astro:actions";

  document.querySelector("#search")?.addEventListener("click", async () => {
    const { data, error } = await actions.searchProducts({ query: "astro" });
    if (error) return console.error(error);
    console.log(data);
  });
</script>

Call from server:

---
import { actions } from "astro:actions";
const { data, error } = await Astro.callAction(actions.searchProducts, { query: "astro" });
---
<pre>{JSON.stringify(data, null, 2)}</pre>

API Endpoints

// src/pages/api/hello.ts
import type { APIRoute } from "astro";

export const GET: APIRoute = async ({ request, cookies, locals }) => {
  return new Response(JSON.stringify({ message: "Hello" }), {
    headers: { "Content-Type": "application/json" },
  });
};

export const POST: APIRoute = async ({ request }) => {
  const body = await request.json();
  return new Response(JSON.stringify({ received: body }), { status: 201 });
};

Middleware

// src/middleware.ts
import { defineMiddleware, sequence } from "astro:middleware";

const withAuth = defineMiddleware(async (context, next) => {
  const session = context.cookies.get("session");
  context.locals.user = session ? { id: "u1", name: "Alex" } : null;
  return next();
});

const withRequestId = defineMiddleware(async (context, next) => {
  context.locals.requestId = crypto.randomUUID();
  return next();
});

export const withAuth);

View Transitions

Use <ClientRouter /> (replaces legacy <ViewTransitions />):

---
import { ClientRouter } from "astro:transitions";
---

<html lang="en">
  <head>
    <ClientRouter />
  </head>
  <body>
    <header transition:persist>
      <nav transition:animate="slide">
        <a href="/">Home</a>
        <a href="/blog">Blog</a>
      </nav>
    </header>
    <main transition:name="page-content">
      <slot />
    </main>
  </body>
</html>

• transition:persist — keep state across navigations
• transition:animate — control animation style
• transition:name — pair elements across pages

Adapters

Required for any server features (SSR, actions, server islands, API routes with request context).

// astro.config.mjs
import vercel from "@astrojs/vercel/serverless";

export default defineConfig({
  adapter: vercel(),
  output: "server",
});

Options: @astrojs/node, @astrojs/vercel, @astrojs/netlify, @astrojs/cloudflare

Common Mistakes

• Forgetting client:* directives — framework components are static HTML by default, interactive code won't run.
• Exposing secrets with PUBLIC_ prefix — only browser-safe values belong there.
• Using old v4 content collection patterns — v5+ requires a loader in defineCollection().
• Missing getStaticPaths() for dynamic routes in static builds.
• Using output: "hybrid" — removed in Astro v5; use static + per-route prerender = false.
• Mixing output: "static" with server features (actions, server islands) without installing an adapter.
• Overusing client:load — prefer client:idle or client:visible for better performance.
• Using server:defer for content that could be built statically.
• Putting global CSS in scoped <style> blocks and expecting it to affect other components.

Practical Defaults

1. Start with static .astro components
2. Add client islands only around interactive UI
3. Use content collections for structured local content
4. Use output: "static" unless the app is mostly request-driven
5. Add prerender = false only on routes that need server rendering
6. Use actions for validated forms and server mutations
7. Use middleware for shared request state (auth, locale)
8. Install the adapter early once you introduce any server feature