Learning Astro - Architecture & Patterns

#Introduction

A newly started project always feels tidy — the problems appear as the project grows: hundreds of pages, dozens of components, and many team members. Episode 17 covers the architecture and patterns that keep an Astro project easy to understand as it grows.

You will learn how to organize files scalably, design reusable component patterns and content architecture, compose static pages with dynamic islands, and apply patterns that make team collaboration easier.

Good architecture is not about having many rules — it is about consistency that makes decisions automatic.

#File Organization and Scalable Project Structure

#A Structure That Grows

Start from the default structure and add layers as needs arise:

src/
├── components/
│   ├── ui/          # tombol, input, badge
│   ├── layout/      # navbar, footer, sidebar
│   └── feature/     # komponen per fitur
├── layouts/
├── pages/
├── lib/             # fungsi dan utilities
├── content/
└── styles/

The ui, layout, and feature separation gives every component type a clear home. The lib folder holds pure logic that is tested separately.

#Consistent Naming Conventions

Pick one convention and stick to it: components in PascalCase (Navbar.astro), utilities in camelCase (formatTanggal.ts), and pages in kebab-case for URLs. Consistency makes file search fast and collaboration frictionless.

#Reusable UI Patterns and Content Architecture

#Components with Clear Props

A good reusable component has minimal props and predictable behavior. Follow the composition pattern: small components do one thing, then get assembled into larger components.

Pola komposisi komponen

---
import Tombol from "./ui/Tombol.astro";
---
 
<Tombol variant="primary" size="lg" onClick="..." label="Daftar" />

The Tombol component above hides styling complexity behind the variant and size props — its usage is consistent across the whole site.

#Strong Content Architecture

Design the content architecture before the content exists: clear collection schemas, a limited tag taxonomy, and a sensible page hierarchy. Good content architecture tells writers where to put content and readers where to find it.

#Composing Static Pages and Dynamic Islands

#Separate Static and Dynamic

An Astro page should be mostly static, with small islands for the parts that are truly interactive. The recommended pattern:

Halaman statis dengan island

---
import Base from "../layouts/Base.astro";
import Pencarian from "../components/Pencarian.tsx";
---
 
<Base title="Beranda">
  <h1>Selamat datang</h1>
  <p>Konten statis yang cepat dan tanpa JavaScript.</p>
  <Pencarian client:visible />
</Base>

The Base layout wraps the content, the main content stays static, and only Pencarian becomes an interactive island. This pattern keeps the whole page light.

#Limit the Number of Islands per Page

An architectural rule of thumb: at most a few islands per page. More islands mean more JavaScript and complexity. If a page needs a lot of interaction, ask again whether another framework fits better.

#Maintainable Project Patterns for Teams

#Pattern: Feature Folders

Organizing by feature lets team members work in clear domains. Each feature has its own components, utilities, and tests. For large projects, consider splitting into a monorepo workspace (Astro Mono).

#Pattern: Shared Utilities and Constants

Centralize cross-feature logic in src/lib: date formatting functions, slug helpers, navigation constants, and category mappings. A single source of truth reduces duplication and inconsistency.

Util bersama di src/lib

export function formatTanggal(t: Date): string {
  return new Intl.DateTimeFormat("id-ID", {
    dateStyle: "long",
  }).format(t);
}
 
export const KATEGORI = ["tutorial", "opini", "berita"] as const;

formatTanggal and the KATEGORI constant are used from many components. By centralizing them, a format change only needs to happen once.

#Pattern: Documentation and ADRs

Record important architecture decisions (Architecture Decision Records) — like adapter choices, content patterns, or naming conventions. Short documentation saves the team from unnecessary re-discussion.

#Conclusion

Episode 17 equips you with architecture and patterns for a growing project: file organization with ui, layout, and feature separation, reusable components with clear props, content architecture designed in advance, static pages composed with a limited number of islands, and patterns for team collaboration.

The key takeaways:

• A clear folder structure keeps the project easy to understand.
• Naming consistency speeds up search and collaboration.
• Reusable components hide complexity behind props.
• Large static pages with small islands preserve performance.
• Limit the number of interactive islands per page.
• Centralize utilities and constants in src/lib.

In the next episode 18, we will cover extensibility and custom integrations: custom integrations and plugins for Astro, using third-party libraries and frameworks, extending the build pipeline with custom scripts, and interoperability across the frontend ecosystem. Your creativity will go beyond Astro's built-in limits.